Conduyt Dashboard API

openapi: 3.2.0
info:
  title: Conduyt Dashboard 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: Dashboard
  description: Dashboard summary metrics
paths:
  /dashboard:
    get:
      operationId: getDashboard
      summary: Get dashboard summary metrics
      description: 'The counts and totals are cached per server instance for 60 seconds per account, role and visibility scope; for 60 seconds after that a cached copy is still answered while one recompute runs in the background. Under that, every instance shares the last computation of the same account and scope (stored server-side, no person or deal data). A shared copy under 3 minutes old is answered as is, an older one is answered while one recompute runs after the response. Every list with a person or a deal (recent activity, needs follow-up, stale deals, overdue tasks, workload names) is read live on every request. generatedAt says when the counts were read and aggregatesAgeMs how old they were when this response was sent. fresh=1 recomputes now. When the numbers cannot be read in time (another request computing a scope''s numbers for the first time, the shared cache unable to coordinate, or this request''s own computation out of time) the answer is a retryable 503 dashboard_computing with Retry-After. MCP and CLI parity for this 503 is tracked under board #602.'
      tags:
      - Dashboard
      responses:
        '200':
          description: Dashboard data (contacts count, deals, revenue, tasks, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataEnvelope'
        '503':
          description: 'dashboard_computing: the numbers could not be read for this request in time: another request is computing this account and scope''s numbers for the first time, the shared cache cannot coordinate right now, or this request''s own computation ran out of its time budget (its claim came back nearly spent, or it was stopped at its deadline, possibly after some of its reads). No numbers are answered and nothing this request read is stored; ask again after Retry-After.'
          headers:
            Retry-After:
              description: Seconds to wait before asking again.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardComputingError'
      parameters:
      - name: fresh
        in: query
        required: false
        description: '1 (or true) recomputes the dashboard now instead of answering from the 60-second cache, and stores the result. 0, false or absent: the cache may answer. Any other value, or two different values, is a 400.'
        schema:
          type: string
components:
  schemas:
    DataEnvelope:
      type: object
      properties:
        data:
          description: Response payload (shape varies by endpoint)
    DashboardComputingError:
      description: '(#566b) GET /dashboard: the numbers could not be read for this request in time (another request computing them, the shared cache unable to coordinate, or this request''s own computation out of time); retryable.'
      type: object
      required:
      - error
      - code
      properties:
        error:
          type: string
        code:
          type: string
          enum:
          - dashboard_computing
  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