honkio-ca Pricing API

openapi: 3.2.0
info:
  title: HonkIO Pricing API
  description: 'Canadian-focused SMS gateway API.


    ## Canadian Compliance

    - **CASL**: All commercial messages require consent. Use `/v1/compliance/consents` to record.

    - **DNCL**: CRTC Do Not Call List checking is coming soon (not yet enforced).

    - **PIPEDA / Quebec Law 25**: Data is stored in Canada (ca-central-1). Requests are processed in the United States in transit. Right-to-erasure available.


    ## Authentication

    Provide your API key via `Authorization: Bearer mk_live_...` or `X-API-Key: mk_live_...`.

    Test keys never send, never charge and can''t change live data; they work before your first top-up.


    ## Rate limits

    100 requests per second per account. Every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.


    ## Pagination

    Shape follows the route family, not one convention across the API: documented here rather than changed. Messages listings return `{ data, meta: { page, limit, total, pages } }`. Contacts, Contact Groups, Lists and Verify listings return `{ data, total, limit, offset }`. Compliance consent and opt-out listings accept `page`/`limit` and return `{ data }`, with no total. Account transactions use a cursor: pass `before`, get back `has_more`.'
  version: 1.0.0
  contact:
    name: HonkIO Support
    email: support@honkio.ca
servers:
- url: https://api.honkio.ca
  description: Production
- url: http://localhost:3000
  description: Local development
security:
- apiKey: []
- apiKeyHeader: []
tags:
- name: Pricing
  description: Current per-send prices, so an integrator can quote a cost before sending
paths:
  /v1/pricing:
    get:
      summary: Current per-send prices in CAD cents
      tags:
      - Pricing
      security: []
      responses:
        '200':
          description: Current prices. All amounts are CAD cents.
          content:
            application/json:
              schema:
                description: Current prices. All amounts are CAD cents.
                type: object
                properties:
                  message_cost_cents:
                    type: integer
                    description: 'Charged per SMS part, counted the way the carrier splits the body: typographic quotes, dashes and ellipses are smart-encoded to GSM-7 (160 characters, then 153 per part); emoji and most accented letters force Unicode parts (70, then 67). The charge is settled to the carrier''s part count after the send. Bodies over 10 parts are refused with 422 MESSAGE_TOO_LONG before any charge.'
                  verification_upcharge_cents:
                    type: integer
                    description: Added once to a verification, on top of the OTP's own segment cost.
                  verification_cost_cents:
                    type: integer
                    description: 'What a typical single-part verification costs: message_cost_cents + verification_upcharge_cents. A long or non-GSM app_name can push the OTP to two parts and raise this; the charge is settled to the carrier''s part count once the OTP is accepted.'
                  phone_number_upfront_cost_cents:
                    type: integer
                    description: The first month's rent for a local number, charged when it is provisioned.
                  phone_number_monthly_cost_cents:
                    type: integer
                    description: Recurring monthly rent for a local number.
                  phone_number_activation_fee_cents:
                    type: integer
                    description: One-time activation fee charged with the first month on every number (local and toll-free). Not refunded on release. A local number's first charge is phone_number_upfront_cost_cents + phone_number_activation_fee_cents.
                  inbound_message_cost_cents:
                    type: integer
                    description: Charged per segment of each inbound SMS received on a provisioned number, using the carrier's part count. Keyword traffic the carrier requires (STOP, START, HELP) is not charged.
                  email_price_millicents:
                    type: integer
                    description: 'Charged per accepted email recipient (to, cc and bcc each count), in CAD millicents: thousandths of a cent, so 250 is $0.0025, or $2.50 per 1,000. The first email_attachment_included_bytes of attachments per recipient are included. Test-mode sends are free. Absent while email sending is not available.'
                  email_attachment_included_bytes:
                    type: integer
                    description: Attachment bytes included in email_price_millicents, per recipient.
                  email_attachment_price_millicents_per_mb:
                    type: integer
                    description: Charged per recipient for every started MB (1,048,576 bytes) of attachments above the included bytes, in CAD millicents. A 10 MiB attachment to one recipient at the defaults is 250 + 8 × 200 = 1,850 millicents ($0.0185).
                  email_attachment_max_bytes:
                    type: integer
                    description: Maximum attachment bytes per email, in total and per file (413 EMAIL_ATTACHMENT_TOO_LARGE above it). At most 10 files per email.
                  email_inbound_price_millicents:
                    type: integer
                    description: 'Charged per received email, in CAD millicents: thousandths of a cent, so 250 is $0.0025. Covers the first email_inbound_included_bytes of the message. Charged on receipt whatever the balance; mail rejected as a virus or over the daily cap is free. Absent while email sending is not available.'
                  email_inbound_included_bytes:
                    type: integer
                    description: Bytes of a received message (the raw message, headers and encoded attachments included) covered by email_inbound_price_millicents.
                  email_inbound_price_millicents_per_mb:
                    type: integer
                    description: Charged for every started MB (1,048,576 bytes) of a received message above email_inbound_included_bytes, in CAD millicents. A 10 MiB message at the defaults is 250 + 9 × 200 = 2,050 millicents ($0.0205). 0 means received mail is charged the base price only.
      operationId: getV1Pricing
      x-operation-id-source: derived
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Use `mk_live_...` for production or `mk_test_...` for testing.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Alternative to the Authorization header: send `mk_live_...` or `mk_test_...` as X-API-Key directly.'