Conduyt Notifications API

openapi: 3.2.0
info:
  title: Conduyt Notifications API
  version: 1.0.0
  description: 'The Conduyt CRM API provides programmatic access to your CRM data including

    contacts, companies, deals, pipelines, tasks, notes, automations, invoices,

    email sequences, and more.


    ## Authentication


    All authenticated endpoints require a Bearer token (API key) in the

    `Authorization` header:


    ```

    Authorization: Bearer cdy_

    ```


    API keys are generated in **Settings > API Keys** within the Conduyt

    dashboard. Keys use the `cdy_` prefix and are hashed with bcrypt on

    creation — the full key is shown exactly once at creation time.


    Session cookie authentication (`conduyt_session`) is also supported for

    browser-based clients but is not recommended for integrations.


    ## Rate Limiting


    API keys enforce a per-key rate limit. New keys default to 100 requests per

    minute and can be configured at creation time or with PATCH `/api-keys/{id}`.

    Some public and provider-facing endpoints also enforce stricter per-IP or

    per-account limits. When exceeded, the API returns `429 Too Many Requests`

    with a `Retry-After` header indicating seconds until the next allowed

    request.


    | Endpoint Group | Limit |

    |---------------------|---------------------|

    | API keys | Default 100 / min per key |

    | Login/reset | 5 / min per IP |

    | Registration | 3 / hour per IP |

    | Contact/Deal create | 30 / min per IP |

    | Inbound messages | 120 / min per account/IP |


    ## Pagination


    List endpoints support cursor-based pagination via query parameters:


    - `page` — Page number (default: 1)

    - `per_page` — Items per page (default: 50, max: 200)

    - `limit` — Accepted as an alias of `per_page` on `GET /contacts`; if both are

    sent they must carry the same value.


    A page size above the maximum, a non-integer, a value below 1, or a

    pagination key repeated with different values is rejected with `400`

    (the message names the parameter and the rule); nothing is silently

    clamped or ignored.


    Responses include a `meta` object: `{ page, per_page, total }`.


    An operation that documents its own pagination rules follows those instead.

    `GET /sms-providers/options` pages with an opaque `cursor` and a `limit`

    that is capped at 50 rather than rejected; its responses carry

    `meta: { nextCursor, truncated }`.


    ## Response Format


    All successful responses wrap data in a `data` envelope:

    ```json

    { "data": { ... } }

    ```


    Error responses use:

    ```json

    { "error": "Human-readable error message" }

    ```


    ## Multi-Tenancy


    Conduyt is multi-tenant. All data is scoped to the authenticated user''s

    current account. API keys are bound to a specific account at creation time.


    ## Webhook Events


    Outbound webhooks fire on events including:

    `contact.created`, `contact.updated`, `contact.deleted`,

    `deal.created`, `deal.updated`, `deal.won`, `deal.lost`,

    `task.created`, `task.completed`, `note.created`,

    `appointment.created`, `appointment.updated`,

    `form.submitted`, `invoice.paid`


    Payloads are signed with HMAC-SHA256 using the webhook''s secret. Retry

    schedule: 1m, 5m, 30m, 2h, 12h, 72h (7 total attempts including the initial delivery).'
  contact:
    name: Conduyt Support
    url: https://conduyt.app
    email: support@conduyt.app
  license:
    name: Proprietary
    url: https://conduyt.app/terms
servers:
- url: https://conduyt.app/api/v1
  description: Production
security:
- BearerAuth: []
tags:
- name: Notifications
  description: In-app notifications
paths:
  /notifications:
    get:
      operationId: listNotifications
      summary: List notifications
      tags:
      - Notifications
      parameters:
      - name: isRead
        in: query
        required: false
        description: Query parameter read by this route.
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
          default: 1
          minimum: 1
        x-default-provenance: handler_literal
      - name: per_page
        in: query
        required: false
        description: Items per page (max 200)
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
        x-default-provenance: handler_literal
      - name: type
        in: query
        required: false
        description: Query parameter read by this route.
        schema:
          type: string
      responses:
        '200':
          description: Paginated notifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      data: {}
                      meta: {}
                    required:
                    - data
                    - meta
                required:
                - data
    post:
      operationId: createNotification
      summary: Create a notification
      tags:
      - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - title
              - message
              properties:
                userId:
                  type: string
                  format: uuid
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  description: Defaults to the caller when omitted
                type:
                  type: string
                  minLength: 1
                  maxLength: 64
                  description: Notification type. Built-in types are documented in the API catalog; custom integration types are allowed.
                title:
                  type: string
                  minLength: 1
                  maxLength: 200
                message:
                  type: string
                  minLength: 1
                  maxLength: 1000
                metadata:
                  type: object
                  additionalProperties: {}
                  description: Capped at 50 top-level keys and 10KB At most 50 keys and 10240 bytes as UTF-8 JSON; otherwise a 400.
                url:
                  type: string
                  maxLength: 500
                  description: Same-origin app path opened from push/notification clicks
                push:
                  type: boolean
                  description: Set false to skip web-push fan-out
      responses:
        '200':
          description: Success
          x-generated-status: true
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      skipped:
                        type: boolean
                      reason:
                        type: string
                      type: {}
                    required:
                    - skipped
                    - reason
                    - type
                required:
                - data
        '201':
          description: Notification created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataEnvelope'
      parameters: []
  /notifications/{id}:
    patch:
      operationId: markNotificationRead
      summary: Mark a notification as read
      tags:
      - Notifications
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isRead:
                  type: boolean
      responses:
        '200':
          description: Notification updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataEnvelope'
  /notifications/read-all:
    post:
      operationId: markAllNotificationsRead
      summary: Mark all notifications as read
      tags:
      - Notifications
      responses:
        '200':
          description: All notifications marked as read
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      updated: {}
                    required:
                    - updated
                required:
                - data
      parameters: []
  /users/{id}/notifications:
    get:
      operationId: getUserNotificationPreferences
      summary: Get user notification preferences
      tags:
      - Notifications
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Notification preferences
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      userId: {}
                      accountId: {}
                      preferences: {}
                    required:
                    - userId
                    - accountId
                    - preferences
                required:
                - data
    patch:
      operationId: updateUserNotificationPreferences
      summary: Update user notification preferences
      tags:
      - Notifications
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - preferences
              properties:
                preferences:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      inApp:
                        type: boolean
                      email:
                        type: boolean
                      sms:
                        type: boolean
                      push:
                        type: boolean
      responses:
        '200':
          description: Notification preferences updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      userId: {}
                      accountId: {}
                      preferences: {}
                    required:
                    - userId
                    - accountId
                    - preferences
                required:
                - data
  /notifications/profiles:
    get:
      operationId: listNotificationProfiles
      summary: List notification profiles
      tags:
      - Notifications
      responses:
        '200':
          description: Notification profiles
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      profiles: {}
                    required:
                    - profiles
                required:
                - data
      parameters: []
    put:
      operationId: replaceNotificationProfiles
      summary: Replace notification profiles
      tags:
      - Notifications
      responses:
        '200':
          description: Notification profiles saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      profiles: {}
                    required:
                    - profiles
                required:
                - data
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - profiles
              properties:
                profiles:
                  maxItems: 20
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                        maxLength: 80
                      name:
                        type: string
                        minLength: 1
                        maxLength: 120
                      description:
                        anyOf:
                        - type: string
                          maxLength: 500
                        - type: 'null'
                      preferences:
                        type: object
                        additionalProperties:
                          type: object
                          properties:
                            inApp:
                              type: boolean
                            email:
                              type: boolean
                            sms:
                              type: boolean
                            push:
                              type: boolean
                    required:
                    - id
                    - name
                    - preferences
    post:
      operationId: applyNotificationProfile
      summary: Apply notification profile
      tags:
      - Notifications
      responses:
        '200':
          description: Notification profile applied
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      applied:
                        type: boolean
                      profile: {}
                    required:
                    - applied
                    - profile
                required:
                - data
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - profileId
              properties:
                profileId:
                  type: string
                  minLength: 1
  /notifications/digest:
    get:
      operationId: getNotificationDigestSettings
      summary: Get notification digest settings
      tags:
      - Notifications
      responses:
        '200':
          description: Notification digest settings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      digest: {}
                    required:
                    - digest
                required:
                - data
      parameters: []
    put:
      operationId: updateNotificationDigestSettings
      summary: Update notification digest settings
      tags:
      - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - enabled
              - frequency
              - hour
              properties:
                enabled:
                  type: boolean
                frequency:
                  type: string
                  enum:
                  - daily
                  - weekly
                hour:
                  type: integer
                  minimum: 0
                  maximum: 23
      responses:
        '200':
          description: Notification digest settings updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      digest: {}
                    required:
                    - digest
                required:
                - data
      parameters: []
components:
  schemas:
    DataEnvelope:
      type: object
      properties:
        data:
          description: Response payload (shape varies by endpoint)
  parameters:
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Resource UUID
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key authentication. Generate keys in Settings > API Keys.

        Keys use the `cdy_` prefix.


        Example: `Authorization: Bearer cdy_a1b2c3d4e5f6...`

        '
x-mcp:
  transport:
  - stdio
  - http
  orchestration: code
  endpoint_tools: hidden