Stalwart HTTP overview API

openapi: 3.1.0
info:
  title: Stalwart HTTP overview API
  version: '2026-10-28'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-28: 19 operation(s) read from 2 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Stalwart has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 7
    documentation: 37
    pages-with-code: 12
    pages-read: 21
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-28'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://stalw.art/docs/http/access-control
  - https://stalw.art/docs/http/api
  x-docs-section: http
servers:
- url: https://get.stalw.art
paths:
  /.well-known/jmap:
    get:
      operationId: get_well_known_jmap
      tags:
      - API
      summary: GET /.well-known/jmap
      x-source: https://stalw.art/docs/http/access-control
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -i https://mail.example.com/.well-known/jmap . \n If the server is no longer reachable for administration, start it in\
          \ recovery mode, where the rules are not applied, and correct the expression. \n Examples Section titled “Examples” \n The following\
          \ rule serves /api/only to requests from 127.0.0.1 , and answers all others with 404 : \n { \"allowedEndpoints\" : { \"match\" : { \"\
          0\" : { \"if\" : \" starts_"
  /api/account:
    get:
      operationId: get_api_account
      tags:
      - Api
      summary: Returns the authenticated account’s permissions, the server edition and the preferred locale.
      x-source: https://stalw.art/docs/http/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiAccountResponse'
      x-evidence:
        kind: documentation
  /api/auth:
    post:
      operationId: post_api_auth
      tags:
      - Api
      summary: Authenticates a user, and completes an OAuth authorisation request or a device authorisation with the result.
      x-source: https://stalw.art/docs/http/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiAuthRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiAuthResponse'
      x-evidence:
        kind: documentation
  /api/auth/client:
    get:
      operationId: get_api_auth_client
      tags:
      - Api
      summary: Returns the details of the client that started a sign‑in.
      x-source: https://stalw.art/docs/http/api
      parameters:
      - name: user_code
        in: query
        required: false
        schema:
          type: string
        description: If present, describes the client of a pending device authorisation.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiAuthClientResponse'
      x-evidence:
        kind: documentation
  /api/calendar/rsvp:
    post:
      operationId: post_api_calendar_rsvp
      tags:
      - Api
      summary: Reads or answers a calendar invitation through an RSVP link.
      x-source: https://stalw.art/docs/http/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiCalendarRsvpRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiCalendarRsvpResponse'
      x-evidence:
        kind: documentation
  /api/discover/{email}:
    get:
      operationId: get_api_discover_email
      tags:
      - Api
      summary: Returns the OpenID Connect discovery document for the account email.
      x-source: https://stalw.art/docs/http/api
      parameters:
      - name: email
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/live/delivery/{target}:
    get:
      operationId: get_api_live_delivery_target
      tags:
      - Api
      summary: Tests delivery to a domain or address, and streams each step as Server‑Sent Events.
      x-source: https://stalw.art/docs/http/api
      parameters:
      - name: target
        in: path
        required: true
        schema:
          type: string
      - name: timeout
        in: query
        required: false
        schema:
          type: string
        description: Timeout in seconds for each network operation (default 30).
      - name: token
        in: query
        required: false
        schema:
          type: string
        description: Token from /api/token/delivery.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiLiveDeliveryTargetResponse'
      x-evidence:
        kind: documentation
  /api/live/metrics:
    get:
      operationId: get_api_live_metrics
      tags:
      - Api
      summary: Streams the current values of the server metrics at a fixed interval, as Server‑Sent Events.
      x-source: https://stalw.art/docs/http/api
      parameters:
      - name: token
        in: query
        required: false
        schema:
          type: string
        description: Token from /api/token/metrics.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/live/tracing:
    get:
      operationId: get_api_live_tracing
      tags:
      - Api
      summary: Streams server events as they occur, as Server‑Sent Events.
      x-source: https://stalw.art/docs/http/api
      parameters:
      - name: token
        in: query
        required: false
        schema:
          type: string
        description: Token from /api/token/tracing.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/schema:
    get:
      operationId: get_api_schema
      tags:
      - Api
      summary: Redirects (302) to /api/schema/{hash}, where {hash} is the SHA‑256 digest of the configuration schema of the running server.
      x-source: https://stalw.art/docs/http/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/schema/{hash}:
    get:
      operationId: get_api_schema_hash
      tags:
      - Api
      summary: Returns the JSON Schema of the server configuration
      description: Authenticated endpoint that returns the configuration schema; response is gzipped and cacheable.
      x-source: https://stalw.art/docs/http/api
      parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/token/{kind}:
    get:
      operationId: get_api_token_kind
      tags:
      - Api
      summary: Issues a short‑lived token for one /api/live/* stream.
      x-source: https://stalw.art/docs/http/api
      parameters:
      - name: kind
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiTokenKindResponse'
      x-evidence:
        kind: documentation
  /calendar/rsvp:
    get:
      operationId: get_calendar_rsvp
      tags:
      - Calendar
      summary: The RSVP page for calendar invitations, while HTTP RSVP is enabled
      description: Serves the RSVP HTML page.
      x-source: https://stalw.art/docs/http/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /form:
    post:
      operationId: post_form
      tags:
      - Form
      summary: Contact form submission
      description: Endpoint for submitting contact form data.
      x-source: https://stalw.art/docs/http/api
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /healthz/live:
    get:
      operationId: get_healthz_live
      tags:
      - Healthz
      summary: Returns 200 while the process is running
      description: Anonymous liveness probe.
      x-source: https://stalw.art/docs/http/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /healthz/ready:
    get:
      operationId: get_healthz_ready
      tags:
      - Healthz
      summary: Returns 200 when the data store is available, otherwise 503
      description: Anonymous readiness probe.
      x-source: https://stalw.art/docs/http/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /logo:
    get:
      operationId: get_logo
      tags:
      - Logo
      summary: The branding logo, while an Enterprise license is active
      description: Returns the server branding logo.
      x-source: https://stalw.art/docs/http/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /metrics/prometheus:
    get:
      operationId: get_metrics_prometheus
      tags:
      - Metrics
      summary: Prometheus metrics, when the Prometheus exporter is enabled
      description: Protected with HTTP Basic authentication when credentials are configured.
      x-source: https://stalw.art/docs/http/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /robots.txt:
    get:
      operationId: get_robots_txt
      tags:
      - Robots
      summary: Disallows all crawling
      description: Standard robots.txt file that blocks all crawlers.
      x-source: https://stalw.art/docs/http/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
security:
- bearer: []
components:
  schemas:
    GetApiAccountResponse:
      type: object
      properties:
        permissions:
          type: string
          description: Array of the account’s effective permissions.
        edition:
          type: string
          description: '"enterprise" when an Enterprise license is active, otherwise "community".'
        locale:
          type: string
          description: Language tag, e.g. en-US.
    PostApiAuthRequest:
      type: object
      properties:
        type:
          type: string
          description: Either "authCode" or "authDevice" to select the request shape.
        accountName:
          type: string
          description: Account name or email address.
        accountSecret:
          type: string
          description: Password or app password.
        mfaToken:
          type: string
          description: One‑time code, sent on a retry after an mfaRequired response.
        query:
          type: string
          description: The query string of the OAuth authorisation request.
        consent:
          type: string
          description: True when the user approved access.
        code:
          type: string
          description: The user code shown by the device, issued by POST /auth/device.
      required:
      - type
    PostApiAuthResponse:
      type: object
      properties:
        type:
          type: string
          description: Indicates the response kind (authenticated, redirect, invalid, verified, denied, mfaRequired, expired, failure).
        location:
          type: string
          description: Redirect URI with appropriate parameters for the response type.
        error:
          type: string
          description: Error code for failure cases.
        description:
          type: string
          description: Human‑readable description of the error.
    GetApiAuthClientResponse:
      type: object
      properties:
        name:
          type: string
          description: Client name.
        logo:
          type: string
          description: URL of the client logo.
        clientHost:
          type: string
          description: Host of the client.
        redirectHost:
          type: string
          description: Redirect host.
        scopes:
          type: string
          description: Labels of the requested scopes.
        verified:
          type: string
          description: Whether the client is verified.
        consentRequired:
          type: string
          description: Whether consent is required.
        denyLocation:
          type: string
          description: Location to send the user to if denied.
        error:
          type: string
          description: OAuth error code on failure.
        description:
          type: string
          description: Optional error description.
        redirect:
          type: string
          description: True if a redirect location is provided.
    PostApiCalendarRsvpRequest:
      type: object
      properties:
        token:
          type: string
          description: The i parameter of the RSVP link.
        partstat:
          type: string
          description: accepted, declined or tentative (case‑insensitive).
        comment:
          type: string
          description: Note for the organiser; trimmed to 512 characters.
      required:
      - token
    PostApiCalendarRsvpResponse:
      type: object
      properties:
        type:
          type: string
          description: One of "invitation", "recorded", or "error".
        invitation:
          type: string
          description: Event details and attendee status when type is invitation.
        recorded:
          type: string
          description: Stored partstat when type is recorded.
        error:
          type: string
          description: Reason code such as invalidLink, invalidPartStat, expired, etc.
    GetApiLiveDeliveryTargetResponse:
      type: object
      properties:
        event:
          type: string
          description: SSE event name (always "event").
        data:
          type: string
          description: JSON array with step objects; final step is {"type":"completed"}.
    GetApiTokenKindResponse:
      type: object
      properties:
        token:
          type: string
          description: Plain‑text token valid for 60 seconds.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
tags:
- name: API
- name: Api
- name: Calendar
- name: Form
- name: Healthz
- name: Logo
- name: Metrics
- name: Robots