Primitive Wake API

openapi: 3.1.0
info:
  title: Primitive Account Wake API
  version: 1.0.0
  description: "Primitive is email infrastructure for AI agents. The Primitive API lets you manage domains, emails, webhook endpoints,\nfilters, and account settings programmatically.\n\n## Authentication\n\nMost endpoints require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer prim_<your_api_key>\nAuthorization: Bearer prim_oat_<oauth_access_token>\n```\n\nAPI keys and OAuth access tokens are org-scoped. Create and manage them in your dashboard\nunder Settings > API Keys. CLI login plus CLI/agent signup endpoints\nexplicitly declare `security: []`; they do not require an API key because\nthey are used to create OAuth CLI sessions.\n\n## Rate Limiting\n\nThe API enforces a sliding window rate limit of **120 requests per\n60 seconds** per organization. When exceeded, the API returns `429`\nwith a `Retry-After` header indicating how many seconds to wait.\n\n## Pagination\n\nList endpoints use cursor-based pagination. Responses include a\n`meta` object with `total`, `limit`, and `cursor` fields. Pass the\n`cursor` value as a query parameter to fetch the next page. When\n`cursor` is `null`, there are no more results.\n\n## Response Format\n\nAll responses use a consistent envelope:\n\n```json\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": { \"total\": 42, \"limit\": 50, \"cursor\": \"...\" }\n}\n```\n\nErrors follow the same pattern:\n\n```json\n{\n  \"success\": false,\n  \"error\": { \"code\": \"not_found\", \"message\": \"Email not found\" }\n}\n```\n\n## Webhook signing\n\nOutbound webhook deliveries (configured via the `endpoints` API)\nare signed so receivers can verify they came from Primitive and\nhave not been tampered with in transit. The signing scheme is\ndeliberately simple so it can be reimplemented in any language\nin a few lines. The Node SDK's `verifyWebhookSignature` helper\nis the reference implementation; the wire details below let you\nwrite a verifier in Python, Go, Ruby, etc. without reading our\nsource.\n\n**Header**: `Primitive-Signature: t=<unix-seconds>,v1=<hex>`\n\nA legacy `MyMX-Signature` header is also sent on every delivery\nwith the same value, retained for back-compatibility with\nintegrations written before the rename. New code should read\n`Primitive-Signature`.\n\n**Signed string**: `${timestamp}.${rawBody}` where `timestamp`\nis the Unix-seconds integer from the `t=` parameter and\n`rawBody` is the exact bytes of the HTTP request body BEFORE\nany JSON decoding. Verify against the raw body, not a\nre-serialized parse, or you will silently mismatch on\ninsignificant whitespace.\n\n**Signature**: HMAC-SHA256 of the signed string, hex-encoded\n(lowercase). Use the account's webhook secret as the HMAC key,\nas a UTF-8 byte sequence.\n\n**Secret**: returned by `GET /account/webhook-secret`. The\nstring looks base64-shaped (e.g. `XNHBBW8VqoBjRfNs1tkZj11jTk...`)\nbut is NOT base64; use it AS-IS as a UTF-8 string for the HMAC\nkey. Base64-decoding before HMAC will silently produce\nmismatched signatures.\n\n**Tolerance**: by convention, reject deliveries whose `t=`\ntimestamp is more than 5 minutes off your wall-clock to defend\nagainst replay attacks. The Node SDK's helper enforces this by\ndefault.\n\n**Verification recipe** (any language):\n\n```\n1. Read the raw HTTP body (do not parse).\n2. Read `Primitive-Signature: t=<ts>,v1=<sig>`.\n3. Reject if abs(now - ts) > 300 seconds.\n4. expected = HMAC_SHA256_hex(secret_utf8, f\"{ts}.{rawBody}\")\n5. Constant-time compare expected to sig. Reject if not equal.\n```\n\nFor Node, use `verifyWebhookSignature` from\n`@primitivedotdev/sdk/webhook` (or the higher-level\n`handleWebhook` helper if you want a one-liner). For other\nlanguages, the recipe above is everything you need.\n\nTest deliveries: `POST /endpoints/{id}/test` triggers a fake\ndelivery to your endpoint URL, signed with your real account\nsecret, so you can confirm verification end-to-end without\nneeding real inbound mail. The test response carries the exact\n`signature` header value sent on the wire so you can compare\nstrings directly.\n\n\n## Errors\n\nEvery error response is the same JSON envelope (`{ \"success\": false, \"error\": { \"code\", \"message\" } }`), served as `application/json` with HTTP status codes, following the RFC 7807 problem-details shape. The `error.code` is a stable machine-readable string and `error.message` is human-readable.\n\n## Authorization and roles\n\nAccess is governed by organization role-based access control. Every organization member holds one of three roles — `owner`, `admin`, or `member` — and a credential inherits a role. **API keys** always act at `member` level, regardless of the role of the user who created them, so an API key can never perform owner- or admin-only actions. **OAuth access tokens** act with the authorizing user's current organization role, resolved on each request. Every operation in this spec is part of the member-level surface, so any valid credential can call it. Organization administration that is not part of this API — billing and organization settings — requires an `owner` or `admin` and is performed in the dashboard. Fine-grained per-key scopes (e.g. a send-only or read-only key) are on the roadmap; today the role model is the unit of access control.\n\n## Versioning\n\nThe current stable API is **v1**. All endpoints are served under `/v1/` and are covered by a backward-compatibility guarantee: existing fields and status codes will not change without a deprecation notice.\n\nBreaking changes are announced at least 6 months in advance via changelog and email. Deprecated operations and fields are marked `x-deprecated: true` in the spec and carry a plain-English description of the replacement. The `v1` path prefix is guaranteed stable indefinitely; backward-compatible additions (new optional fields, new endpoints) may be made at any time without a version bump."
  contact:
    name: Primitive
    url: https://primitive.dev
  license:
    name: Proprietary
    url: https://primitive.dev/terms
  x-stability-level: stable
  x-deprecation-policy: 'Breaking changes are announced at least 6 months in advance. Deprecated fields carry x-deprecated: true. The current stable version is v1.'
servers:
- url: https://api.primitive.dev/v1
  description: Canonical API host (PRIMITIVE_API_BASE_URL). Carries every public API operation.
tags:
- name: Wake
  description: 'Wake scheduling: schedule and send typed wake commands to your own

    functions over real DKIM-signed email on a cron cadence, and manage the

    per-target allowlist that authorizes which senders may wake a function.

    '
paths:
  /wake/schedules:
    get:
      operationId: listWakeSchedules
      summary: List wake schedules
      description: Returns the org's wake.dispatch schedules.
      tags:
      - Wake
      responses:
        '200':
          description: List of wake schedules
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    success:
                      type: boolean
                      const: true
                  required:
                  - success
                  - data
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        description: A cron schedule that sends a wake.dispatch command to a function.
                        properties:
                          id:
                            type: string
                            format: uuid
                          from_address:
                            type:
                            - string
                            - 'null'
                            description: The sending identity the wake is signed as.
                          target_address:
                            type: string
                            description: The function address the wake is delivered to.
                          command:
                            type: string
                          args:
                            type: object
                            additionalProperties: true
                          cron_expr:
                            type: string
                            description: 5-field cron expression.
                          timezone:
                            type: string
                            description: IANA timezone the cron is evaluated in.
                          next_run_at:
                            type: string
                            format: date-time
                          last_run_at:
                            type:
                            - string
                            - 'null'
                            format: date-time
                          enabled:
                            type: boolean
                          note:
                            type:
                            - string
                            - 'null'
                          created_at:
                            type: string
                            format: date-time
                          updated_at:
                            type: string
                            format: date-time
                        required:
                        - id
                        - target_address
                        - command
                        - cron_expr
                        - timezone
                        - next_run_at
                        - enabled
                        - created_at
                        - updated_at
          headers:
            ratelimit-limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: integer
                minimum: 1
                example: 120
            ratelimit-remaining:
              description: Remaining requests in the current window.
              schema:
                type: integer
                minimum: 0
                example: 118
            ratelimit-reset:
              description: Unix timestamp (seconds) when the current window resets.
              schema:
                type: integer
                example: 1700000060
            ratelimit-policy:
              description: Rate-limit policy in `limit;w=seconds` format, e.g. `120;w=60`.
              schema:
                type: string
                example: 120;w=60
        '401':
          $ref: '#/components/responses/Unauthorized'
          description: Invalid or missing API key
      security:
      - BearerAuth: []
    post:
      operationId: createWakeSchedule
      summary: Create a wake schedule
      description: 'Create a cron schedule that sends a wake.dispatch command to one of your

        own function addresses. `from` and `to` must differ (no self-dispatch);

        the cron expression and IANA timezone are validated and the first fire

        time is computed without firing immediately.

        '
      tags:
      - Wake
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                from_address:
                  type: string
                  description: Sending identity (must be a domain the org can sign).
                target_address:
                  type: string
                  description: Your function address (must differ from from_address).
                command:
                  type: string
                  minLength: 1
                  maxLength: 200
                args:
                  type: object
                  additionalProperties: true
                  description: Optional JSON object passed through to the woken function.
                cron_expr:
                  type: string
                  minLength: 1
                  maxLength: 120
                timezone:
                  type: string
                  minLength: 1
                  maxLength: 64
                  default: UTC
                note:
                  type: string
                  maxLength: 2000
              required:
              - from_address
              - target_address
              - command
              - cron_expr
      responses:
        '201':
          description: Wake schedule created
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    success:
                      type: boolean
                      const: true
                  required:
                  - success
                  - data
                - type: object
                  properties:
                    data:
                      type: object
                      description: A cron schedule that sends a wake.dispatch command to a function.
                      properties:
                        id:
                          type: string
                          format: uuid
                        from_address:
                          type:
                          - string
                          - 'null'
                          description: The sending identity the wake is signed as.
                        target_address:
                          type: string
                          description: The function address the wake is delivered to.
                        command:
                          type: string
                        args:
                          type: object
                          additionalProperties: true
                        cron_expr:
                          type: string
                          description: 5-field cron expression.
                        timezone:
                          type: string
                          description: IANA timezone the cron is evaluated in.
                        next_run_at:
                          type: string
                          format: date-time
                        last_run_at:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        enabled:
                          type: boolean
                        note:
                          type:
                          - string
                          - 'null'
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                      required:
                      - id
                      - target_address
                      - command
                      - cron_expr
                      - timezone
                      - next_run_at
                      - enabled
                      - created_at
                      - updated_at
        '400':
          $ref: '#/components/responses/ValidationError'
          description: Invalid request parameters
        '401':
          $ref: '#/components/responses/Unauthorized'
          description: Invalid or missing API key
      security:
      - BearerAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional client-supplied idempotency key. Retrying a request with the same key returns the original result instead of performing the action a second time; if omitted the server derives one from the canonical payload hash. Safe to retry network failures without duplicating side effects.
        schema:
          type: string
          minLength: 1
          maxLength: 255
  /wake/schedules/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Resource UUID
    get:
      operationId: getWakeSchedule
      summary: Get a wake schedule
      tags:
      - Wake
      responses:
        '200':
          description: The wake schedule
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    success:
                      type: boolean
                      const: true
                  required:
                  - success
                  - data
                - type: object
                  properties:
                    data:
                      type: object
                      description: A cron schedule that sends a wake.dispatch command to a function.
                      properties:
                        id:
                          type: string
                          format: uuid
                        from_address:
                          type:
                          - string
                          - 'null'
                          description: The sending identity the wake is signed as.
                        target_address:
                          type: string
                          description: The function address the wake is delivered to.
                        command:
                          type: string
                        args:
                          type: object
                          additionalProperties: true
                        cron_expr:
                          type: string
                          description: 5-field cron expression.
                        timezone:
                          type: string
                          description: IANA timezone the cron is evaluated in.
                        next_run_at:
                          type: string
                          format: date-time
                        last_run_at:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        enabled:
                          type: boolean
                        note:
                          type:
                          - string
                          - 'null'
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                      required:
                      - id
                      - target_address
                      - command
                      - cron_expr
                      - timezone
                      - next_run_at
                      - enabled
                      - created_at
                      - updated_at
          headers:
            ratelimit-limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: integer
                minimum: 1
                example: 120
            ratelimit-remaining:
              description: Remaining requests in the current window.
              schema:
                type: integer
                minimum: 0
                example: 118
            ratelimit-reset:
              description: Unix timestamp (seconds) when the current window resets.
              schema:
                type: integer
                example: 1700000060
            ratelimit-policy:
              description: Rate-limit policy in `limit;w=seconds` format, e.g. `120;w=60`.
              schema:
                type: string
                example: 120;w=60
        '401':
          $ref: '#/components/responses/Unauthorized'
          description: Invalid or missing API key
        '404':
          $ref: '#/components/responses/NotFound'
          description: Resource not found
      security:
      - BearerAuth: []
      description: Get a wake schedule
    patch:
      operationId: updateWakeSchedule
      summary: Update a wake schedule
      description: 'Update a schedule''s command, args, cadence, addresses, note, or enabled

        state. Changing the cadence (or re-enabling) recomputes the next fire time.

        '
      tags:
      - Wake
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                enabled:
                  type: boolean
                command:
                  type: string
                  minLength: 1
                  maxLength: 200
                args:
                  type: object
                  additionalProperties: true
                cron_expr:
                  type: string
                  minLength: 1
                  maxLength: 120
                timezone:
                  type: string
                  minLength: 1
                  maxLength: 64
                from_address:
                  type: string
                target_address:
                  type: string
                note:
                  type:
                  - string
                  - 'null'
                  maxLength: 2000
      responses:
        '200':
          description: Updated wake schedule
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    success:
                      type: boolean
                      const: true
                  required:
                  - success
                  - data
                - type: object
                  properties:
                    data:
                      type: object
                      description: A cron schedule that sends a wake.dispatch command to a function.
                      properties:
                        id:
                          type: string
                          format: uuid
                        from_address:
                          type:
                          - string
                          - 'null'
                          description: The sending identity the wake is signed as.
                        target_address:
                          type: string
                          description: The function address the wake is delivered to.
                        command:
                          type: string
                        args:
                          type: object
                          additionalProperties: true
                        cron_expr:
                          type: string
                          description: 5-field cron expression.
                        timezone:
                          type: string
                          description: IANA timezone the cron is evaluated in.
                        next_run_at:
                          type: string
                          format: date-time
                        last_run_at:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        enabled:
                          type: boolean
                        note:
                          type:
                          - string
                          - 'null'
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                      required:
                      - id
                      - target_address
                      - command
                      - cron_expr
                      - timezone
                      - next_run_at
                      - enabled
                      - created_at
                      - updated_at
          headers:
            ratelimit-limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: integer
                minimum: 1
                example: 120
            ratelimit-remaining:
              description: Remaining requests in the current window.
              schema:
                type: integer
                minimum: 0
                example: 118
            ratelimit-reset:
              description: Unix timestamp (seconds) when the current window resets.
              schema:
                type: integer
                example: 1700000060
            ratelimit-policy:
              description: Rate-limit policy in `limit;w=seconds` format, e.g. `120;w=60`.
              schema:
                type: string
                example: 120;w=60
        '400':
          $ref: '#/components/responses/ValidationError'
          description: Invalid request parameters
        '401':
          $ref: '#/components/responses/Unauthorized'
          description: Invalid or missing API key
        '404':
          $ref: '#/components/responses/NotFound'
          description: Resource not found
      security:
      - BearerAuth: []
    delete:
      operationId: deleteWakeSchedule
      summary: Delete a wake schedule
      tags:
      - Wake
      responses:
        '200':
          description: Resource deleted
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    success:
                      type: boolean
                      const: true
                  required:
                  - success
                  - data
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        deleted:
                          type: boolean
                          const: true
                      required:
                      - deleted
          headers:
            ratelimit-limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: integer
                minimum: 1
                example: 120
            ratelimit-remaining:
              description: Remaining requests in the current window.
              schema:
                type: integer
                minimum: 0
                example: 118
            ratelimit-reset:
              description: Unix timestamp (seconds) when the current window resets.
              schema:
                type: integer
                example: 1700000060
            ratelimit-policy:
              description: Rate-limit policy in `limit;w=seconds` format, e.g. `120;w=60`.
              schema:
                type: string
                example: 120;w=60
        '401':
          $ref: '#/components/responses/Unauthorized'
          description: Invalid or missing API key
        '404':
          $ref: '#/components/responses/NotFound'
          description: Resource not found
      security:
      - BearerAuth: []
      description: Delete a wake schedule
  /wake/schedules/{id}/run:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Resource UUID
    post:
      operationId: runWakeSchedule
      summary: Run a wake schedule now
      description: 'Fire the schedule immediately, sending one wake.dispatch via the same

        signed-send path as a scheduled fire. Does not change the schedule''s next

        fire time.

        '
      tags:
      - Wake
      responses:
        '200':
          description: The wake interaction that was emitted
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    success:
                      type: boolean
                      const: true
                  required:
                  - success
                  - data
                - type: object
                  properties:
                    data:
                      type: object
                      additionalProperties: true
          headers:
            ratelimit-limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: integer
                minimum: 1
                example: 120
            ratelimit-remaining:
              description: Remaining requests in the current window.
              schema:
                type: integer
                minimum: 0
                example: 118
            ratelimit-reset:
              description: Unix timestamp (seconds) when the current window resets.
              schema:
                type: integer
                example: 1700000060
            ratelimit-policy:
              description: Rate-limit policy in `limit;w=seconds` format, e.g. `120;w=60`.
              schema:
                type: string
                example: 120;w=60
        '400':
          $ref: '#/components/responses/ValidationError'
          description: Invalid request parameters
        '401':
          $ref: '#/components/responses/Unauthorized'
          description: Invalid or missing API key
        '404':
          $ref: '#/components/responses/NotFound'
          description: Resource not found
      security:
      - BearerAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional client-supplied idempotency key. Retrying a request with the same key returns the original result instead of performing the action a second time; if omitted the server derives one from the canonical payload hash. Safe to retry network failures without duplicating side effects.
        schema:
          type: string
          minLength: 1
          maxLength: 255
  /wake/authorizations:
    get:
      operationId: listWakeAuthorizations
      summary: List wake authorizations
      description: 'Returns the per-target allowlist grants that authorize which senders may

        wake a function. Optionally filter by the target endpoint.

        '
      tags:
      - Wake
      parameters:
      - name: recipient_endpoint_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Only return grants for this target endpoint
      responses:
        '200':
          description: List of wake authorizations
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    success:
                      type: boolean
                      const: true
                  required:
                  - success
                  - data
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        description: A per-target allowlist grant authorizing a sender to wake a function.
                        properties:
                          id:
                            type: string
                            format: uuid
                          recipient_endpoint_id:
                            type: string
                            format: uuid
                          allowed_sender_domain:
                            type: string
                          allowed_sender_address:
                            type:
                            - string
                            - 'null'
                          allowed_commands:
                            type:
                            - array
                            - 'null'
                            items:
                              type: string
                          enabled:
                            type: boolean
                          note:
                            type:
                            - string
                            - 'null'
                          created_at:
                            type: string
                            format: date-time
                        required:
                        - id
                        - recipient_en

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/primitive/refs/heads/main/openapi/primitive-wake-api-openapi.yml