openapi: 3.0.3
info:
  title: Grinfi.io API
  description: >
    Complete API reference for Grinfi.io — the all-in-one LinkedIn & email
    outreach platform.

    Use this API to manage your CRM contacts, run outreach automations, send
    messages, and integrate Grinfi with your own tools.


    ## Authentication

    All requests require a Bearer token in the `Authorization` header.

    1. Log in at [leadgen.grinfi.io](https://leadgen.grinfi.io/)

    2. Go to [Settings → API Keys](https://leadgen.grinfi.io/settings/api-keys)

    3. Copy your key and pass it as:
       ```
       Authorization: Bearer YOUR_API_KEY
       ```


    ## Pagination

    List endpoints support `limit` (default 20) and `offset` (default 0) query
    parameters. Responses include `total` count and `has_more` boolean.


    ## Filtering

    Most list endpoints accept a `filter` object. Supported value types:

    | Type | Example | SQL equivalent | |------|---------|----------------| |
    Scalar | `"status": "ok"` | `= 'ok'` | | Array | `"status": ["ok",
    "pending"]` | `IN ('ok', 'pending')` | | Object | `"created_at": {">=":
    "2024-01-01"}` | `>= '2024-01-01'` | | `"is_null"` | `"email": "is_null"` |
    `IS NULL` | | `"is_not_null"` | `"email": "is_not_null"` | `IS NOT NULL` |

    Supported operators: `=`, `!=`, `<`, `<=`, `>`, `>=`, `<>`


    ## Rate Limits

    API requests are rate-limited per account. If you exceed the limit, you'll
    receive a `429` response. Use exponential backoff when retrying.
  version: 2.0.0
  contact:
    name: Grinfi.io Support
    url: https://grinfi.io
    email: support@grinfi.io
  license:
    name: Copyright
    url: https://grinfi.io/terms
x-tagGroups:
  - name: CRM
    tags:
      - Contacts
      - Companies
      - Lists
      - Tags
      - Pipeline
      - Custom Fields
      - Notes
  - name: Outreach
    tags:
      - Automations
      - Tasks
      - Sender Profiles
  - name: Messaging
    tags:
      - LinkedIn Messages
      - Emails
      - Mailboxes
  - name: Integrations
    tags:
      - AI Templates
tags:
  - name: Contacts
    description: >
      Manage your CRM contacts (leads). Search, create, update, and organize
      contacts across lists and pipeline stages.
  - name: Companies
    description: >
      Manage company records in your CRM. Companies can be linked to contacts
      and enriched with additional data from LinkedIn.
  - name: Lists
    description: >
      Organize contacts into lists. Every contact must belong to a list. Use
      lists to segment your audience for outreach campaigns.
  - name: Tags
    description: >
      Label contacts and companies with custom tags for easy filtering and
      segmentation.
  - name: Pipeline
    description: >
      Define and manage pipeline stages to track where each contact stands in
      your sales or outreach process.
  - name: Custom Fields
    description: >
      Extend contact and company records with custom data fields. Store any
      additional information relevant to your workflow.
  - name: Notes
    description: |
      Add internal notes to contacts or companies for your team's reference.
  - name: Automations
    description: >
      Manage outreach automation sequences. Automations define multi-step
      workflows that send LinkedIn messages, emails, and perform other actions
      on a schedule.
  - name: Tasks
    description: >
      Create and manage outreach tasks such as sending LinkedIn messages or
      emails. Tasks can be created manually or generated by automations.
  - name: Sender Profiles
    description: >
      Sender profiles represent the LinkedIn and email accounts used to send
      outreach messages. Each profile links a LinkedIn browser and/or email
      mailbox.
  - name: LinkedIn Messages
    description: >
      Send and retrieve LinkedIn messages through your connected sender
      profiles.
  - name: Emails
    description: |
      Send and retrieve emails through your connected mailboxes.
  - name: Mailboxes
    description: >
      Manage email mailboxes (SMTP/IMAP, Gmail, Outlook) used for sending and
      receiving emails in outreach campaigns.
  - name: AI Templates
    description: >
      Manage AI message templates for generating personalized outreach messages
      at scale.
servers:
  - url: https://leadgen.grinfi.io
    description: Production
security:
  - bearerAuth: []
paths:
  /leads/api/leads/lookup-one:
    post:
      summary: Find a contact
      description: >
        Look up a single contact by LinkedIn ID, email address, or name +
        company combination. At least one identifier must be provided. This is
        useful for checking if a contact already exists before creating a new
        one.
      operationId: findOneContact
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                linkedin_id:
                  type: string
                  nullable: true
                  description: LinkedIn profile URL or member ID.
                  example: john-doe-123456
                email:
                  type: string
                  nullable: true
                  description: Email address to search by.
                  example: john@example.com
                name:
                  type: string
                  nullable: true
                  description: Full name of the contact.
                  example: John Doe
                company_name:
                  type: string
                  nullable: true
                  description: Company name (required when searching by name).
                  example: Acme Inc
                disable_aggregation:
                  type: boolean
                  description: Skip enrichment data aggregation in the response.
              anyOf:
                - required:
                    - linkedin_id
                - required:
                    - email
                - required:
                    - name
                    - company_name
            example:
              linkedin_id: john-doe-123456
      responses:
        '200':
          description: Contact found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead'
        '404':
          description: No matching contact found.
        '422':
          description: Validation error — provide at least one identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /leads/api/leads/search:
    post:
      summary: Search contacts
      description: >
        Search contacts using advanced filters with pagination and sorting. Use
        this to find contacts by any combination of fields — name, company,
        email status, pipeline stage, tags, and more.
      operationId: searchContacts
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: object
                  description: >
                    Filter criteria. Supports scalar values (equals), arrays
                    (IN), objects with operators (`>=`, `<=`, etc.),
                    `"is_null"`, `"is_not_null"`.
                  example:
                    company_name: Acme Inc
                    email_status: ok
                limit:
                  type: integer
                  minimum: 1
                  default: 20
                  description: Number of results to return.
                  example: 20
                offset:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Number of results to skip.
                  example: 0
                order_field:
                  type: string
                  default: created_at
                  description: Field to sort by.
                  example: name
                order_type:
                  type: string
                  enum:
                    - asc
                    - desc
                  default: desc
                  description: Sort direction.
                  example: asc
                disable_aggregation:
                  type: boolean
                  default: false
                  description: Skip enrichment data aggregation.
            example:
              filter:
                company_name: Acme Inc
                email_status: ok
              limit: 20
              offset: 0
              order_field: created_at
              order_type: desc
      responses:
        '200':
          description: Paginated list of matching contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/lead'
                  limit:
                    type: integer
                    example: 20
                  offset:
                    type: integer
                    example: 0
                  total:
                    type: integer
                    example: 142
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /leads/api/leads/{uuid}:
    get:
      summary: Get a contact
      description: Retrieve full details of a contact by their UUID.
      operationId: getLead
      tags:
        - Contacts
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Contact details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead'
        '404':
          description: Contact not found.
    put:
      summary: Update a contact
      description: >
        Update one or more fields on an existing contact. Only include the
        fields you want to change.
      operationId: updateLead
      tags:
        - Contacts
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  example: John
                last_name:
                  type: string
                  example: Doe
                company_name:
                  type: string
                  example: Acme Inc
                ln_id:
                  type: string
                  nullable: true
                  description: LinkedIn member ID.
                  example: ACoAAAB6GuQBOXo75numqJfM9u08uHgjOSo4p9U
                sn_id:
                  type: string
                  nullable: true
                  description: Sales Navigator ID.
                  example: ACwAAAB6GuQBEz2TMHbG4sa7Nw5wSi7cJXMQkPI
                linkedin:
                  type: string
                  nullable: true
                  description: LinkedIn profile handle.
                  example: john-doe-123456
                email:
                  type: string
                  format: email
                  example: john.doe@example.com
                about:
                  type: string
                  description: Bio or description.
                domain:
                  type: string
                  description: Company domain (used for email discovery).
                  example: acme.com
                headline:
                  type: string
                  nullable: true
                  example: VP of Sales at Acme Inc
                position:
                  type: string
                  nullable: true
                  example: VP of Sales
                raw_address:
                  type: string
                  nullable: true
                  example: San Francisco, CA, USA
      responses:
        '200':
          description: Updated contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead'
        '404':
          description: Contact not found.
    delete:
      summary: Delete a contact
      description: >-
        Permanently delete a contact by UUID. This creates a background deletion
        job.
      operationId: deleteLead
      tags:
        - Contacts
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '204':
          description: Contact deleted.
        '422':
          description: Unable to process deletion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /leads/api/leads/upsert:
    post:
      summary: Create or update a contact
      description: >
        Create a new contact in a list, or update an existing one if found. The
        contact is identified by `linkedin_id`. If the contact already exists
        and `update_if_exists` is true, their data will be updated. Optionally
        move the contact to the specified list with `move_to_list`.
      operationId: upsertContact
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - lead
                - list_uuid
              properties:
                lead:
                  allOf:
                    - $ref: '#/components/schemas/create-lead-fields'
                    - type: object
                      required:
                        - linkedin_id
                custom_fields:
                  type: object
                  additionalProperties: true
                  description: Custom field values as key-value pairs.
                  example:
                    field_position: CTO
                    field_experience: 10 years
                list_uuid:
                  type: string
                  description: Target list UUID.
                  example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                update_if_exists:
                  type: boolean
                  default: true
                  description: Update the contact if it already exists.
                move_to_list:
                  type: boolean
                  default: false
                  description: Move existing contact to the specified list.
            example:
              lead:
                linkedin_id: john-doe-123456
                first_name: John
                last_name: Doe
                company_name: Acme Inc
                email: john@acme.com
              list_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              update_if_exists: true
      responses:
        '200':
          description: Contact created or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lead'
        '422':
          description: Validation or duplicate error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /leads/api/leads/mass-action:
    put:
      summary: Bulk action on contacts
      description: >
        Perform a bulk operation on contacts matching a filter. Supported
        actions include changing pipeline stage, assigning/removing tags, moving
        to a list, and deleting.
      operationId: leadsMassAction
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - filter
              properties:
                type:
                  type: string
                  description: >
                    Action type: `contact_change_pipeline_stage`,
                    `contact_assign_tag`, `contact_remove_tag`,
                    `contact_move_to_list`, `contact_delete`,
                    `contact_mark_read`.
                  example: contact_change_pipeline_stage
                payload:
                  type: object
                  description: Action-specific payload.
                  example:
                    pipeline_stage_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                filter:
                  type: object
                  description: Filter to select contacts.
                  properties:
                    all:
                      type: boolean
                    ids:
                      type: array
                      items:
                        type: string
                  example:
                    ids:
                      - uuid-1
                      - uuid-2
      responses:
        '200':
          description: Action dispatched.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /leads/api/companies:
    get:
      summary: List companies
      description: >
        Retrieve a paginated list of companies in your CRM. Supports filtering
        by name, domain, industry, and other fields.
      operationId: listCompanies
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
        - in: query
          name: filter
          schema:
            type: object
            properties:
              q:
                type: string
                description: Search query.
          description: Filters for company search.
      responses:
        '200':
          description: Paginated list of companies.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/company'
                  limit:
                    type: integer
                    example: 20
                  offset:
                    type: integer
                    example: 0
                  total:
                    type: integer
                    example: 58
    post:
      summary: Create companies
      description: >
        Create one or more company records. Optionally assign them to lists and
        a data source.
      operationId: createCompanies
      tags:
        - Companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - companies
              properties:
                companies:
                  type: array
                  description: Array of company objects to create.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        example: Acme Inc
                      domain:
                        type: string
                        example: acme.com
                      website:
                        type: string
                        example: https://acme.com
                      linkedin:
                        type: string
                        example: acme-inc
                      industry:
                        type: string
                        example: Technology
                      employees_range:
                        type: string
                        example: 51-200
                      hq_raw_address:
                        type: string
                        example: San Francisco, CA
                list_uuids:
                  type: array
                  items:
                    type: string
                  description: List UUIDs to assign companies to.
                data_source_uuid:
                  type: string
            example:
              companies:
                - name: Acme Inc
                  domain: acme.com
                  industry: Technology
              list_uuids:
                - a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Created companies.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/company'
  /leads/api/companies/{uuid}:
    get:
      summary: Get a company
      description: Retrieve full details of a company by UUID.
      operationId: getCompany
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Company details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/company'
        '404':
          description: Company not found.
    put:
      summary: Update a company
      description: Update one or more fields on an existing company.
      operationId: updateCompany
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Acme Inc
                domain:
                  type: string
                  example: acme.com
                website:
                  type: string
                  example: https://acme.com
                linkedin:
                  type: string
                  example: acme-inc
                ln_id:
                  type: integer
                  description: LinkedIn company numeric ID.
                industry:
                  type: string
                  example: Technology
                employees_range:
                  type: string
                  example: 51-200
                hq_raw_address:
                  type: string
                  example: San Francisco, CA
                phone:
                  type: string
                about:
                  type: string
                lead_status_uuid:
                  type: string
                  description: Pipeline stage UUID.
      responses:
        '200':
          description: Updated company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/company'
        '404':
          description: Company not found.
    delete:
      summary: Delete a company
      description: Permanently delete a company by UUID.
      operationId: deleteCompany
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '204':
          description: Company deleted.
        '422':
          description: Unable to process deletion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /leads/api/companies/lookup:
    post:
      summary: Lookup companies
      description: >
        Find companies by LinkedIn ID, website URL, or name. Pass an array of
        lookup criteria — each item should contain at least one identifier.
      operationId: lookupCompanies
      tags:
        - Companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - lookups
              properties:
                lookups:
                  type: array
                  items:
                    type: object
                    properties:
                      ln_id:
                        type: string
                      linkedin:
                        type: string
                      website:
                        type: string
                      name:
                        type: string
            example:
              lookups:
                - linkedin: acme-inc
                - website: acme.com
      responses:
        '200':
          description: Matching companies.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/company'
  /leads/api/companies/leads:
    post:
      summary: Get contacts by companies
      description: >
        Retrieve all contacts belonging to the specified companies. Returns an
        object mapping company UUIDs to arrays of contacts.
      operationId: getCompanyLeads
      tags:
        - Companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - uuids
              properties:
                uuids:
                  type: array
                  items:
                    type: string
                  description: Array of company UUIDs.
            example:
              uuids:
                - a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Contacts grouped by company UUID.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/lead'
  /leads/api/companies/advanced-enrichment:
    put:
      summary: Enrich companies
      description: >
        Queue advanced enrichment for companies. Provide either a filter to
        select companies or an array of specific company UUIDs. Enrichment uses
        credits from your account balance.
      operationId: enrichCompanies
      tags:
        - Companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: object
                  description: Filter to select companies for enrichment.
                uuids:
                  type: array
                  items:
                    type: string
                  description: Specific company UUIDs to enrich.
            example:
              uuids:
                - a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Enrichment queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Number of companies queued.
        '402':
          description: Insufficient enrichment credits.
  /leads/api/lists:
    get:
      summary: List all lists
      description: >
        Retrieve all contact lists in your account. Lists are used to organize
        contacts into groups for outreach campaigns.
      operationId: listLists
      tags:
        - Lists
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
        - in: query
          name: filter
          schema:
            type: object
            properties:
              q:
                type: string
                nullable: true
                description: Search by list name.
              uuid:
                $ref: '#/components/schemas/mixed-filter-type'
              name:
                $ref: '#/components/schemas/mixed-filter-type'
      responses:
        '200':
          description: List of contact lists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/list'
                  limit:
                    type: integer
                    example: 20
                  offset:
                    type: integer
                    example: 0
                  total:
                    type: integer
                    example: 12
    post:
      summary: Create a list
      description: Create a new contact list.
      operationId: createList
      tags:
        - Lists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Name for the new list.
                  example: CMO Germany
            example:
              name: CMO Germany
      responses:
        '201':
          description: List created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list'
  /leads/api/lists/{uuid}:
    get:
      summary: Get a list
      description: Retrieve details of a specific contact list.
      operationId: getList
      tags:
        - Lists
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: List details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list'
        '404':
          description: List not found.
    put:
      summary: Update a list
      description: Rename an existing contact list.
      operationId: updateList
      tags:
        - Lists
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  example: Updated List Name
      responses:
        '200':
          description: Updated list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list'
    delete:
      summary: Delete a list
      description: Permanently delete a contact list.
      operationId: deleteList
      tags:
        - Lists
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '204':
          description: List deleted.
  /leads/api/tags:
    get:
      summary: List tags
      description: Retrieve all tags in your account.
      operationId: listTags
      tags:
        - Tags
      responses:
        '200':
          description: List of tags.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/tag'
    post:
      summary: Create a tag
      description: Create a new tag with optional color.
      operationId: createTag
      tags:
        - Tags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  example: Hot Lead
                color:
                  type: string
                  description: Hex color code.
                  example: '#ff5733'
      responses:
        '201':
          description: Tag created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tag'
  /leads/api/tags/{uuid}:
    put:
      summary: Update a tag
      description: Update a tag's name or color.
      operationId: updateTag
      tags:
        - Tags
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Warm Lead
                color:
                  type: string
                  example: '#33ff57'
      responses:
        '200':
          description: Updated tag.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tag'
    delete:
      summary: Delete a tag
      description: Permanently delete a tag.
      operationId: deleteTag
      tags:
        - Tags
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '204':
          description: Tag deleted.
  /leads/api/pipeline-stages:
    get:
      summary: List pipeline stages
      description: >
        Retrieve all pipeline stages. Filter by `object` type (lead or company)
        to get stages specific to contacts or companies.
      operationId: listPipelineStages
      tags:
        - Pipeline
      parameters:
        - in: query
          name: object
          schema:
            type: string
            enum:
              - lead
              - company
            default: lead
          description: Filter by object type.
        - in: query
          name: type
          schema:
            type: string
            enum:
              - custom
              - new
              - approaching
              - engaging
              - replied
          description: Filter by stage type.
      responses:
        '200':
          description: List of pipeline stages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/pipeline-stage'
    post:
      summary: Create a pipeline stage
      description: Create a new custom pipeline stage.
      operationId: createPipelineStage
      tags:
        - Pipeline
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - object
                - category
              properties:
                name:
                  type: string
                  example: Demo Booked
                object:
                  type: string
                  enum:
                    - lead
                    - company
                  example: lead
                category:
                  type: string
                  enum:
                    - cold
                    - engaging
                    - positive
                    - negative
                  description: Visual category for the stage.
                  example: positive
                order:
                  type: integer
                  description: Display order.
                  example: 5
      responses:
        '201':
          description: Stage created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pipeline-stage'
  /leads/api/pipeline-stages/{uuid}:
    put:
      summary: Update a pipeline stage
      description: Update a pipeline stage's name, category, or order.
      operationId: updatePipelineStage
      tags:
        - Pipeline
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                category:
                  type: string
                  enum:
                    - cold
                    - engaging
                    - positive
                    - negative
                order:
                  type: integer
      responses:
        '200':
          description: Updated stage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pipeline-stage'
    delete:
      summary: Delete a pipeline stage
      description: Delete a custom pipeline stage.
      operationId: deletePipelineStage
      tags:
        - Pipeline
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '204':
          description: Stage deleted.
  /leads/api/custom-fields:
    get:
      summary: List custom fields
      description: Retrieve all custom field definitions for contacts and companies.
      operationId: listCustomFields
      tags:
        - Custom Fields
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
      responses:
        '200':
          description: List of custom fields.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/custom-field'
    post:
      summary: Create a custom field
      description: Define a new custom field for contacts or companies.
      operationId: createCustomField
      tags:
        - Custom Fields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - object
              properties:
                name:
                  type: string
                  description: Field name.
                  example: Industry Vertical
                object:
                  type: string
                  enum:
                    - lead
                    - company
                  description: Whether this field applies to contacts or companies.
                  example: lead
                order:
                  type: integer
                  description: Display order.
      responses:
        '201':
          description: Custom field created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/custom-field'
  /leads/api/custom-fields/{uuid}:
    put:
      summary: Update a custom field
      description: Update a custom field's name or order.
      operationId: updateCustomField
      tags:
        - Custom Fields
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                order:
                  type: integer
      responses:
        '200':
          description: Updated field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/custom-field'
    delete:
      summary: Delete a custom field
      description: Permanently remove a custom field definition and all its values.
      operationId: deleteCustomField
      tags:
        - Custom Fields
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '204':
          description: Field deleted.
  /leads/api/custom-field-values:
    post:
      summary: Set a custom field value
      description: >
        Set (or update) a custom field value on a contact or company. Pass
        `null` as value to clear the field.
      operationId: upsertCustomFieldValue
      tags:
        - Custom Fields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - custom_field_uuid
                - object_type
                - object_uuid
              properties:
                custom_field_uuid:
                  type: string
                  description: UUID of the custom field.
                object_type:
                  type: string
                  enum:
                    - lead
                    - company
                object_uuid:
                  type: string
                  description: UUID of the contact or company.
                value:
                  type: string
                  nullable: true
                  description: Field value, or null to clear.
                  example: Enterprise
            example:
              custom_field_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              object_type: lead
              object_uuid: b2c3d4e5-f6a7-8901-bcde-f12345678901
              value: Enterprise
      responses:
        '201':
          description: Value set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/custom-field-value'
  /leads/api/notes:
    get:
      summary: List notes
      description: Retrieve notes with pagination.
      operationId: listNotes
      tags:
        - Notes
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
      responses:
        '200':
          description: List of notes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/note'
    post:
      summary: Create a note
      description: Add a note to a contact or company.
      operationId: createNote
      tags:
        - Notes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - object
                - object_uuid
                - note
              properties:
                object:
                  type: string
                  enum:
                    - lead
                    - company
                  example: lead
                object_uuid:
                  type: string
                  description: UUID of the contact or company.
                note:
                  type: string
                  example: Follow up after demo next week.
      responses:
        '201':
          description: Note created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/note'
  /leads/api/notes/{uuid}:
    put:
      summary: Update a note
      description: Update the text of an existing note.
      operationId: updateNote
      tags:
        - Notes
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - note
              properties:
                note:
                  type: string
                  example: Updated note content.
      responses:
        '200':
          description: Updated note.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/note'
    delete:
      summary: Delete a note
      description: Permanently delete a note.
      operationId: deleteNote
      tags:
        - Notes
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '204':
          description: Note deleted.
  /flows/api/flows:
    get:
      summary: List automations
      description: >
        Retrieve all outreach automations in your account. Automations are
        multi-step sequences that send LinkedIn messages, emails, and other
        actions on a schedule.
      operationId: listFlows
      tags:
        - Automations
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
        - in: query
          name: filter
          schema:
            type: object
            properties:
              q:
                type: string
                nullable: true
                description: Search by automation name.
              status:
                $ref: '#/components/schemas/mixed-filter-type'
          description: Filters.
      responses:
        '200':
          description: Paginated list of automations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/flow'
                  limit:
                    type: integer
                    example: 20
                  offset:
                    type: integer
                    example: 0
                  total:
                    type: integer
                    example: 15
                  has_more:
                    type: boolean
  /flows/api/flows/{flowUuid}:
    get:
      summary: Get an automation
      description: Retrieve full details of an automation by UUID.
      operationId: getFlow
      tags:
        - Automations
      parameters:
        - $ref: '#/components/parameters/flowUuid-path'
      responses:
        '200':
          description: Automation details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flow'
        '404':
          description: Automation not found.
    put:
      summary: Update an automation
      description: Update an automation's name, description, or schedule.
      operationId: updateFlow
      tags:
        - Automations
      parameters:
        - $ref: '#/components/parameters/flowUuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Updated Campaign Name
                description:
                  type: string
                schedule:
                  $ref: '#/components/schemas/schedule'
      responses:
        '200':
          description: Updated automation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flow'
    delete:
      summary: Delete an automation
      description: Permanently delete an automation. This cannot be undone.
      operationId: deleteFlow
      tags:
        - Automations
      parameters:
        - $ref: '#/components/parameters/flowUuid-path'
      responses:
        '204':
          description: Automation deleted.
  /flows/api/flows/{flowUuid}/start:
    put:
      summary: Start an automation
      description: >
        Activate an automation so it begins processing contacts and executing
        outreach steps on its schedule.
      operationId: startFlow
      tags:
        - Automations
      parameters:
        - $ref: '#/components/parameters/flowUuid-path'
      responses:
        '200':
          description: Automation started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flow'
        '422':
          description: Cannot start (e.g., archived automation).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /flows/api/flows/{flowUuid}/stop:
    put:
      summary: Stop an automation
      description: >-
        Pause an automation. Contacts already in progress will finish their
        current step.
      operationId: stopFlow
      tags:
        - Automations
      parameters:
        - $ref: '#/components/parameters/flowUuid-path'
      responses:
        '200':
          description: Automation stopped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flow'
  /flows/api/flows/{flowUuid}/archive:
    put:
      summary: Archive an automation
      description: Archive an automation. Archived automations cannot be started.
      operationId: archiveFlow
      tags:
        - Automations
      parameters:
        - $ref: '#/components/parameters/flowUuid-path'
      responses:
        '200':
          description: Automation archived.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flow'
  /flows/api/flows/{flowUuid}/unarchive:
    put:
      summary: Unarchive an automation
      description: Restore an archived automation so it can be started again.
      operationId: unarchiveFlow
      tags:
        - Automations
      parameters:
        - $ref: '#/components/parameters/flowUuid-path'
      responses:
        '200':
          description: Automation unarchived.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flow'
  /flows/api/flows/clone:
    post:
      summary: Clone an automation
      description: >
        Create a copy of an existing automation with a new name. The cloned
        automation will be in a stopped state.
      operationId: cloneFlow
      tags:
        - Automations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - flow_uuid
                - name
              properties:
                flow_uuid:
                  type: string
                  description: UUID of the automation to clone.
                name:
                  type: string
                  example: Campaign Q2 - Copy
                flow_workspace_uuid:
                  type: string
      responses:
        '201':
          description: Cloned automation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flow'
  /flows/api/flows/metrics:
    post:
      summary: Get automation metrics
      description: >
        Retrieve performance metrics for one or more automations — contacts
        added, messages sent, replies received, etc.
      operationId: getFlowMetrics
      tags:
        - Automations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - uuids
              properties:
                uuids:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Metrics per automation.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
  /flows/api/flows/{flowUuid}/leads/{leadUuid}:
    post:
      summary: Add a contact to an automation
      description: >
        Add an existing contact to an automation. The contact will enter the
        automation from the beginning of the sequence.
      operationId: addLeadToFlow
      tags:
        - Automations
      parameters:
        - $ref: '#/components/parameters/flowUuid-path'
        - in: path
          name: leadUuid
          required: true
          schema:
            type: string
          description: Contact UUID.
      responses:
        '204':
          description: Contact added.
        '404':
          description: Automation or contact not found.
  /flows/api/flows/{flowUuid}/add-new-lead:
    post:
      summary: Create a contact and add to automation
      description: >
        Create a new contact and immediately add them to an automation. The
        contact is created in the specified list and starts the automation
        sequence. If `skip_if_lead_exists` is true, existing contacts won't be
        added again.
      operationId: addNewLeadToFlow
      tags:
        - Automations
      parameters:
        - $ref: '#/components/parameters/flowUuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - lead
                - list_uuid
              properties:
                lead:
                  allOf:
                    - $ref: '#/components/schemas/create-lead-fields'
                    - type: object
                      required:
                        - linkedin_id
                custom_fields:
                  type: object
                  additionalProperties: true
                  description: Custom field values.
                  example:
                    field_position: CTO
                list_uuid:
                  type: string
                  description: List UUID for the new contact.
                update_lead_if_exists:
                  type: boolean
                  default: true
                move_to_list:
                  type: boolean
                  default: false
                flow_segment_id:
                  type: integer
                  default: 1
                  description: Automation segment to enter.
                skip_if_lead_exists:
                  type: boolean
                  description: Skip if contact already exists.
            example:
              lead:
                linkedin_id: john-doe-123456
                first_name: John
                last_name: Doe
                company_name: Acme Inc
              list_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              skip_if_lead_exists: true
      responses:
        '200':
          description: Contact skipped (already exists).
          content:
            application/json:
              schema:
                type: object
                properties:
                  reason:
                    type: string
                    example: skipped
        '204':
          description: Contact created and added to automation.
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /flows/api/flows/leads/{leadUuid}/cancel:
    put:
      summary: Cancel contact from specific automations
      description: >
        Remove a contact from specific automations. The contact's progress in
        those automations will be cancelled.
      operationId: cancelLeadFromFlows
      tags:
        - Automations
      parameters:
        - in: path
          name: leadUuid
          required: true
          schema:
            type: string
          description: Contact UUID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - flow_uuids
              properties:
                flow_uuids:
                  type: array
                  items:
                    type: string
                  description: Automation UUIDs to cancel from.
      responses:
        '204':
          description: Contact cancelled from specified automations.
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /flows/api/flows/leads/{leadUuid}/cancel-all:
    put:
      summary: Cancel contact from all automations
      description: Remove a contact from all active automations at once.
      operationId: cancelLeadFromAllFlows
      tags:
        - Automations
      parameters:
        - in: path
          name: leadUuid
          required: true
          schema:
            type: string
          description: Contact UUID.
      responses:
        '204':
          description: Contact cancelled from all automations.
  /flows/api/tasks:
    get:
      summary: List tasks
      description: >
        Retrieve outreach tasks with filtering. Tasks can be manual (created by
        you) or automatic (generated by automations). Filter by `automation` =
        `manual` or `auto`.
      operationId: listTasks
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
        - in: query
          name: automation
          schema:
            type: string
            enum:
              - manual
              - auto
          description: Filter by task source.
        - in: query
          name: status
          schema:
            type: string
            enum:
              - in_progress
              - closed
              - canceled
              - failed
          description: Filter by task status.
        - in: query
          name: type
          schema:
            type: string
          description: Filter by type (e.g. `linkedin_send_message`).
        - in: query
          name: lead_uuid
          schema:
            type: string
          description: Filter by contact UUID.
        - in: query
          name: sender_profile_uuid
          schema:
            type: string
          description: Filter by sender profile.
        - in: query
          name: schedule_at_before
          schema:
            type: string
            format: date-time
          description: Tasks scheduled before this date.
        - in: query
          name: schedule_at_after
          schema:
            type: string
            format: date-time
          description: Tasks scheduled after this date.
      responses:
        '200':
          description: Paginated list of tasks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/task'
                  limit:
                    type: integer
                  offset:
                    type: integer
                  total:
                    type: integer
    post:
      summary: Create a task
      description: >
        Create a manual outreach task. Common types: `linkedin_send_message`,
        `linkedin_send_connection_request`, `linkedin_send_inmail`,
        `linkedin_like_latest_post`, `linkedin_endorse_skills`.
      operationId: createTask
      tags:
        - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - lead_uuid
                - sender_profile_uuid
                - text
                - schedule_at
              properties:
                lead_uuid:
                  type: string
                sender_profile_uuid:
                  type: string
                type:
                  type: string
                  default: linkedin_send_message
                  example: linkedin_send_message
                text:
                  type: string
                  example: Hi John, I'd love to connect!
                note:
                  type: string
                schedule_at:
                  type: string
                  format: date-time
                  example: '2026-03-01T10:00:00.000000Z'
                timezone:
                  type: string
                  default: UTC
            example:
              lead_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              sender_profile_uuid: b2c3d4e5-f6a7-8901-bcde-f12345678901
              type: linkedin_send_message
              text: Hi John, I'd love to connect!
              schedule_at: '2026-03-01T10:00:00.000000Z'
      responses:
        '201':
          description: Task created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/task'
  /flows/api/tasks/{uuid}:
    get:
      summary: Get a task
      description: Retrieve details of a specific task.
      operationId: getTask
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Task details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/task'
        '404':
          description: Task not found.
  /flows/api/tasks/{uuid}/complete:
    put:
      summary: Complete a task
      description: Mark a manual task as completed. Only works for manual tasks.
      operationId: completeTask
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Task completed.
  /flows/api/tasks/{uuid}/cancel:
    put:
      summary: Cancel a task
      description: Cancel a manual task. Only works for manual tasks.
      operationId: cancelTask
      tags:
        - Tasks
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Task cancelled.
  /flows/api/sender-profiles:
    get:
      summary: List sender profiles
      description: >
        Retrieve all sender profiles. A sender profile represents a person (with
        linked LinkedIn account and/or email mailbox) who sends outreach
        messages.
      operationId: listSenderProfiles
      tags:
        - Sender Profiles
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
        - in: query
          name: filter
          schema:
            type: object
            properties:
              q:
                type: string
                nullable: true
              status:
                $ref: '#/components/schemas/mixed-filter-type'
          description: Filters.
      responses:
        '200':
          description: Paginated list of sender profiles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/sender-profile'
                  limit:
                    type: integer
                  offset:
                    type: integer
                  total:
                    type: integer
                  has_more:
                    type: boolean
    post:
      summary: Create a sender profile
      description: Create a new sender profile with a name and optional label.
      operationId: createSenderProfile
      tags:
        - Sender Profiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - first_name
                - last_name
              properties:
                first_name:
                  type: string
                  example: John
                last_name:
                  type: string
                  example: Doe
                label:
                  type: string
                  example: Sales Team - US
                assignee_user_id:
                  type: integer
            example:
              first_name: John
              last_name: Doe
              label: Sales Team - US
      responses:
        '201':
          description: Sender profile created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sender-profile'
  /flows/api/sender-profiles/{uuid}:
    get:
      summary: Get a sender profile
      description: Retrieve details of a sender profile.
      operationId: getSenderProfile
      tags:
        - Sender Profiles
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Sender profile details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sender-profile'
        '404':
          description: Not found.
    put:
      summary: Update a sender profile
      description: Update a sender profile's name, label, or schedule.
      operationId: updateSenderProfile
      tags:
        - Sender Profiles
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
                label:
                  type: string
                schedule:
                  type: object
      responses:
        '200':
          description: Updated sender profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sender-profile'
    delete:
      summary: Delete a sender profile
      description: Permanently delete a sender profile.
      operationId: deleteSenderProfile
      tags:
        - Sender Profiles
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '204':
          description: Deleted.
  /flows/api/sender-profiles/{uuid}/enable:
    put:
      summary: Enable a sender profile
      description: Enable a sender profile so it can be used in automations.
      operationId: enableSenderProfile
      tags:
        - Sender Profiles
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Enabled.
  /flows/api/sender-profiles/{uuid}/disable:
    put:
      summary: Disable a sender profile
      description: Disable a sender profile. It will no longer be used in automations.
      operationId: disableSenderProfile
      tags:
        - Sender Profiles
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Disabled.
  /flows/api/linkedin-messages:
    get:
      summary: List LinkedIn messages
      description: >
        Retrieve LinkedIn messages from your unified inbox. Filter by contact,
        sender profile, conversation, message type (inbox/outbox), and status.
      operationId: listLinkedinMessages
      tags:
        - LinkedIn Messages
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
        - in: query
          name: filter
          style: deepObject
          explode: true
          schema:
            type: object
            properties:
              q:
                type: string
                nullable: true
              lead_uuid:
                $ref: '#/components/schemas/mixed-filter-type'
              sender_profile_uuid:
                $ref: '#/components/schemas/mixed-filter-type'
              type:
                $ref: '#/components/schemas/mixed-filter-type'
              status:
                $ref: '#/components/schemas/mixed-filter-type'
      responses:
        '200':
          description: Paginated list of messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/linkedin-message'
                  limit:
                    type: integer
                  offset:
                    type: integer
                  total:
                    type: integer
                  has_more:
                    type: boolean
    post:
      summary: Send a LinkedIn message
      description: >
        Send a LinkedIn message to a contact through a sender profile. The
        message will be queued and sent via the linked LinkedIn account.
      operationId: sendLinkedInMessage
      tags:
        - LinkedIn Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sender_profile_uuid
                - lead_uuid
                - text
              properties:
                sender_profile_uuid:
                  type: string
                lead_uuid:
                  type: string
                text:
                  type: string
                  example: Hi John, thanks for connecting!
                template_uuid:
                  type: string
                  description: Optional AI template UUID.
                attachments:
                  type: array
                  items:
                    type: object
            example:
              sender_profile_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              lead_uuid: b2c3d4e5-f6a7-8901-bcde-f12345678901
              text: Hi John, thanks for connecting!
      responses:
        '201':
          description: Message queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/linkedin-message'
  /flows/api/linkedin-messages/{uuid}:
    delete:
      summary: Delete a LinkedIn message
      description: Delete a LinkedIn message record.
      operationId: deleteLinkedinMessage
      tags:
        - LinkedIn Messages
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '204':
          description: Deleted.
  /emails/api/emails:
    get:
      summary: List emails
      description: >
        Retrieve emails from your unified inbox. Filter by contact, sender
        profile, mailbox, type (inbox/outbox), status, and date range.
      operationId: listEmails
      tags:
        - Emails
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
        - in: query
          name: filter
          schema:
            type: object
            properties:
              q:
                type: string
                nullable: true
              lead_uuid:
                $ref: '#/components/schemas/mixed-filter-type'
              sender_profile_uuid:
                $ref: '#/components/schemas/mixed-filter-type'
              mailbox_uuid:
                $ref: '#/components/schemas/mixed-filter-type'
              type:
                $ref: '#/components/schemas/mixed-filter-type'
              status:
                $ref: '#/components/schemas/mixed-filter-type'
      responses:
        '200':
          description: List of emails.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/email'
                  limit:
                    type: integer
                  offset:
                    type: integer
                  total:
                    type: integer
  /emails/api/emails/{uuid}:
    get:
      summary: Get an email
      description: Retrieve full details of an email by UUID.
      operationId: getEmail
      tags:
        - Emails
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Email details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email'
        '404':
          description: Email not found.
    delete:
      summary: Delete an email
      description: Delete an email record.
      operationId: deleteEmail
      tags:
        - Emails
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '204':
          description: Deleted.
  /emails/api/emails/send-email:
    post:
      summary: Send an email
      description: |
        Send a new email to a contact through a connected mailbox.
      operationId: sendEmail
      tags:
        - Emails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sender_profile_uuid
                - lead_uuid
                - from_name
                - from_email
                - to_name
                - to_email
                - subject
              properties:
                sender_profile_uuid:
                  type: string
                  format: uuid
                lead_uuid:
                  type: string
                  format: uuid
                from_name:
                  type: string
                  example: John Doe
                from_email:
                  type: string
                  example: john@company.com
                to_name:
                  type: string
                  example: Jane Smith
                to_email:
                  type: string
                  example: jane@acme.com
                cc:
                  type: array
                  items:
                    type: string
                bcc:
                  type: array
                  items:
                    type: string
                subject:
                  type: string
                  example: Quick question about your outreach stack
            example:
              sender_profile_uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              lead_uuid: b2c3d4e5-f6a7-8901-bcde-f12345678901
              from_name: John Doe
              from_email: john@company.com
              to_name: Jane Smith
              to_email: jane@acme.com
              subject: Quick question about your outreach stack
      responses:
        '201':
          description: Email sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  emailDomain:
                    $ref: '#/components/schemas/email'
                  emailBodyDomain:
                    $ref: '#/components/schemas/email-body'
  /emails/api/mailboxes:
    get:
      summary: List mailboxes
      description: >
        Retrieve all email mailboxes (SMTP/IMAP, Gmail, Outlook) configured in
        your account.
      operationId: listMailboxes
      tags:
        - Mailboxes
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
        - in: query
          name: filter
          schema:
            type: object
            properties:
              q:
                type: string
      responses:
        '200':
          description: List of mailboxes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/mailbox'
                  limit:
                    type: integer
                  offset:
                    type: integer
                  total:
                    type: integer
    post:
      summary: Create a mailbox
      description: |
        Add a new SMTP/IMAP mailbox with connection settings.
      operationId: createMailbox
      tags:
        - Mailboxes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - sender_name
                - sender_profile_uuid
              properties:
                email:
                  type: string
                  example: outreach@company.com
                sender_name:
                  type: string
                  example: John from Company
                sender_profile_uuid:
                  type: string
                provider:
                  type: string
                connection_settings:
                  type: object
                  properties:
                    smtp_host:
                      type: string
                    smtp_port:
                      type: integer
                    smtp_username:
                      type: string
                    smtp_password:
                      type: string
                    imap_host:
                      type: string
                    imap_port:
                      type: integer
                    imap_username:
                      type: string
                    imap_password:
                      type: string
                automation_daily_limit:
                  type: integer
                  example: 50
                automation_task_interval:
                  type: integer
                  example: 120
      responses:
        '201':
          description: Mailbox created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mailbox'
  /emails/api/mailboxes/{uuid}:
    get:
      summary: Get a mailbox
      description: Retrieve details of a specific mailbox.
      operationId: getMailbox
      tags:
        - Mailboxes
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Mailbox details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mailbox'
        '404':
          description: Not found.
    put:
      summary: Update a mailbox
      description: >-
        Update mailbox settings such as sender name, daily limits, or connection
        details.
      operationId: updateMailbox
      tags:
        - Mailboxes
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sender_name:
                  type: string
                automation_daily_limit:
                  type: integer
                automation_task_interval:
                  type: integer
                connection_settings:
                  type: object
                custom_tracking_domain_uuid:
                  type: string
      responses:
        '200':
          description: Updated mailbox.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mailbox'
    delete:
      summary: Delete a mailbox
      description: |
        Delete a mailbox. Optionally reassign automations to another mailbox.
      operationId: deleteMailbox
      tags:
        - Mailboxes
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - automation_reassign_mailboxes
              properties:
                automation_reassign_mailboxes:
                  type: boolean
                automation_mailbox_to_reassign:
                  type: string
      responses:
        '204':
          description: Deleted.
  /emails/api/mailboxes/{uuid}/activate:
    put:
      summary: Activate a mailbox
      description: Enable a mailbox so it can send and sync emails.
      operationId: activateMailbox
      tags:
        - Mailboxes
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Activated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mailbox'
  /emails/api/mailboxes/{uuid}/deactivate:
    put:
      summary: Deactivate a mailbox
      description: Disable a mailbox. It will stop sending and syncing emails.
      operationId: deactivateMailbox
      tags:
        - Mailboxes
      parameters:
        - $ref: '#/components/parameters/uuid-path'
      responses:
        '200':
          description: Deactivated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mailbox'
  /flows/api/ai-templates:
    get:
      summary: List AI templates
      description: >
        Retrieve AI message templates for generating personalized outreach
        messages.
      operationId: listAITemplates
      tags:
        - AI Templates
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/order-field'
        - $ref: '#/components/parameters/order-type'
        - in: query
          name: search
          schema:
            type: string
          description: Search by template name.
      responses:
        '200':
          description: List of AI templates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ai-template'
    post:
      summary: Create an AI template
      description: Create a new AI template for generating outreach messages.
      operationId: createAITemplate
      tags:
        - AI Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  example: Personalized Intro
                prompt:
                  type: string
                  example: Write a short LinkedIn connection request to {first_name}...
                body:
                  type: string
                subject:
                  type: string
                fallback_body:
                  type: string
                type:
                  type: string
                enable_validation:
                  type: boolean
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ai-template'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        API key from [Settings -> API
        Keys](https://leadgen.grinfi.io/settings/api-keys).
  schemas:
    error:
      type: object
      properties:
        message:
          type: string
          example: Validation failed for input parameters
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    lead:
      type: object
      description: A contact (lead) in your CRM.
      properties:
        uuid:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        team_id:
          type: integer
        user_id:
          type: integer
          nullable: true
        sender_profile_uuid:
          type: string
          nullable: true
        list_uuid:
          type: string
        data_source_uuid:
          type: string
          nullable: true
        pipeline_stage_uuid:
          type: string
        company_uuid:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
          example: John Doe
        first_name:
          type: string
          nullable: true
          example: John
        last_name:
          type: string
          nullable: true
          example: Doe
        company_name:
          type: string
          nullable: true
          example: Acme Inc
        company_ln_id:
          type: string
          nullable: true
        position:
          type: string
          nullable: true
          example: VP of Sales
        headline:
          type: string
          nullable: true
          example: VP of Sales at Acme Inc
        about:
          type: string
          nullable: true
        avatar_url:
          type: string
          nullable: true
        ln_id:
          type: string
          nullable: true
          description: LinkedIn member ID.
        sn_id:
          type: string
          nullable: true
          description: Sales Navigator ID.
        linkedin:
          type: string
          nullable: true
          example: john-doe-123456
        facebook:
          type: string
          nullable: true
        twitter:
          type: string
          nullable: true
        work_email:
          type: string
          nullable: true
          example: john@acme.com
        personal_email:
          type: string
          nullable: true
        work_phone_number:
          type: string
          nullable: true
        personal_phone_number:
          type: string
          nullable: true
        connections_number:
          type: integer
          nullable: true
        followers_number:
          type: integer
          nullable: true
        primary_language:
          type: string
          nullable: true
        supported_languages:
          type: array
          nullable: true
          items:
            type: string
        has_open_profile:
          type: integer
          nullable: true
        has_verified_profile:
          type: integer
          nullable: true
        has_premium:
          type: integer
          nullable: true
        experience:
          type: array
          nullable: true
          items:
            type: object
            properties:
              title:
                type: string
              company:
                type: string
              start_date:
                type: string
              end_date:
                type: string
        posts:
          type: array
          nullable: true
          items:
            type: object
            properties:
              content:
                type: string
              date:
                type: string
                format: date-time
        educations:
          type: array
          nullable: true
          items:
            type: object
            properties:
              school:
                type: string
              degree:
                type: string
              field_of_study:
                type: string
              start_year:
                type: string
              end_year:
                type: string
        skills:
          type: array
          nullable: true
          items:
            type: string
        raw_address:
          type: string
          nullable: true
          example: San Francisco, CA, USA
        location:
          type: array
          nullable: true
          items:
            type: object
            properties:
              address_string:
                type: string
        tags:
          type: array
          nullable: true
          items:
            type: string
          description: Tag UUIDs.
        status:
          type: string
          example: ok
        linkedin_status:
          type: string
          example: active
        email_status:
          type: string
          nullable: true
        unread_counts:
          type: array
          items:
            type: object
            properties:
              category:
                type: string
              count:
                type: integer
        last_automation_approve_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
    create-lead-fields:
      type: object
      properties:
        linkedin_id:
          type: string
          description: LinkedIn profile URL or member ID.
          example: john-doe-123456
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        company_name:
          type: string
          example: Acme Inc
        ln_id:
          type: string
          nullable: true
        sn_id:
          type: string
          nullable: true
        linkedin:
          type: string
          nullable: true
        email:
          type: string
          format: email
          example: john@acme.com
        about:
          type: string
        domain:
          type: string
          description: Company domain for email discovery.
          example: acme.com
        headline:
          type: string
          nullable: true
        position:
          type: string
          nullable: true
        raw_address:
          type: string
          nullable: true
    company:
      type: object
      description: A company record in your CRM.
      properties:
        uuid:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        team_id:
          type: integer
        user_id:
          type: integer
          nullable: true
        data_source_uuid:
          type: string
          nullable: true
        lead_status_uuid:
          type: string
          nullable: true
          description: Pipeline stage UUID.
        name:
          type: string
          example: Acme Inc
        domain:
          type: string
          nullable: true
          example: acme.com
        website:
          type: string
          nullable: true
          example: https://acme.com
        ln_id:
          type: integer
          nullable: true
          description: LinkedIn company numeric ID.
        linkedin:
          type: string
          nullable: true
          example: acme-inc
        facebook:
          type: string
          nullable: true
        twitter:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        hq_raw_address:
          type: string
          nullable: true
          example: San Francisco, CA, USA
        hq_location:
          type: array
          nullable: true
          items:
            type: object
        logo_url:
          type: string
          nullable: true
        industry:
          type: string
          nullable: true
          example: Technology
        employees_range:
          type: string
          nullable: true
          example: 51-200
        year_established:
          type: integer
          nullable: true
          example: 2015
        about:
          type: string
          nullable: true
        lists:
          type: array
          nullable: true
          items:
            type: string
          description: List UUIDs.
        tags:
          type: array
          nullable: true
          items:
            type: string
          description: Tag UUIDs.
        status:
          type: string
        last_enrich_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
    tag:
      type: object
      properties:
        uuid:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        team_id:
          type: integer
        name:
          type: string
          example: Hot Lead
        color:
          type: string
          nullable: true
          example: '#ff5733'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    pipeline-stage:
      type: object
      properties:
        uuid:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        team_id:
          type: integer
        name:
          type: string
          example: Demo Booked
        object:
          type: string
          enum:
            - lead
            - company
        type:
          type: string
          enum:
            - custom
            - new
            - approaching
            - engaging
            - replied
        category:
          type: string
          enum:
            - cold
            - engaging
            - positive
            - negative
        order:
          type: integer
    custom-field:
      type: object
      properties:
        uuid:
          type: string
        team_id:
          type: integer
        user_id:
          type: integer
        name:
          type: string
          example: Industry Vertical
        object:
          type: string
          enum:
            - lead
            - company
        order:
          type: integer
    custom-field-value:
      type: object
      properties:
        uuid:
          type: string
        team_id:
          type: integer
        custom_field_uuid:
          type: string
        object_type:
          type: string
          enum:
            - lead
            - company
        object_uuid:
          type: string
        value:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    note:
      type: object
      properties:
        uuid:
          type: string
        team_id:
          type: integer
        user_id:
          type: integer
        object:
          type: string
          enum:
            - lead
            - company
        object_uuid:
          type: string
        note:
          type: string
          example: Follow up after demo next week.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    list:
      type: object
      properties:
        uuid:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        team_id:
          type: integer
        name:
          type: string
          example: CMO Germany
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    flow:
      type: object
      properties:
        uuid:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        public_uuid:
          type: string
          nullable: true
        team_id:
          type: integer
        name:
          type: string
          example: DACH CTO Outreach
        flow_workspace_uuid:
          type: string
          nullable: true
        flow_version_uuid:
          type: string
        schedule:
          $ref: '#/components/schemas/schedule'
        description:
          type: string
          nullable: true
        priority:
          type: integer
        status:
          type: string
          description: '`on`, `off`, or `archived`.'
          example: 'on'
        is_public:
          type: boolean
        user_id:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    schedule:
      type: object
      description: Working hours schedule.
      properties:
        timezone:
          type: string
          example: Europe/Berlin
        use_lead_timezone:
          type: boolean
          default: false
        timeblocks:
          type: array
          items:
            type: object
            properties:
              dow:
                type: integer
                description: Day of week (0=Sunday).
              from:
                type: integer
                description: Start time in minutes from midnight.
                example: 540
              to:
                type: integer
                description: End time in minutes from midnight.
                example: 1080
      required:
        - timezone
        - timeblocks
    task:
      type: object
      properties:
        uuid:
          type: string
        team_id:
          type: integer
        user_id:
          type: integer
        lead_uuid:
          type: string
        sender_profile_uuid:
          type: string
        flow_uuid:
          type: string
          nullable: true
        type:
          type: string
          example: linkedin_send_message
        text:
          type: string
        note:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - in_progress
            - closed
            - canceled
            - failed
        automation:
          type: string
          enum:
            - manual
            - auto
        schedule_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    sender-profile:
      type: object
      properties:
        uuid:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        team_id:
          type: integer
        linkedin_server_id:
          type: integer
          nullable: true
        linkedin_browser_uuid:
          type: string
          nullable: true
        linkedin_account_uuid:
          type: string
          nullable: true
        mailbox_uuid:
          type: string
          nullable: true
        assignee_user_id:
          type: integer
          nullable: true
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        label:
          type: string
          nullable: true
          example: Sales Team - US
        status:
          type: string
          example: enabled
        user_id:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    linkedin-message:
      type: object
      properties:
        uuid:
          type: string
        team_id:
          type: integer
        sender_profile_uuid:
          type: string
        linkedin_account_uuid:
          type: string
        linkedin_conversation_uuid:
          type: string
        lead_uuid:
          type: string
        task_pipeline_uuid:
          type: string
          nullable: true
        template_uuid:
          type: string
          nullable: true
        message_hash:
          type: string
          nullable: true
        text:
          type: string
          example: Hi John, thanks for connecting!
        custom_content:
          type: array
          nullable: true
        attachments:
          type: array
          nullable: true
        type:
          type: string
          description: '`inbox` or `outbox`.'
          example: outbox
        automation:
          type: string
          description: '`auto` or `manual`.'
        status:
          type: string
          example: sent
        fail_reason:
          type: string
          nullable: true
        read_at:
          type: string
          format: date-time
          nullable: true
        sent_at:
          type: string
          format: date-time
          nullable: true
        user_id:
          type: integer
    email:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        team_id:
          type: integer
        user_id:
          type: integer
        sender_profile_uuid:
          type: string
          format: uuid
        mailbox_uuid:
          type: string
          format: uuid
        email_body_uuid:
          type: string
          format: uuid
        flow_uuid:
          type: string
          format: uuid
          nullable: true
        lead_uuid:
          type: string
          format: uuid
        status:
          type: string
        type:
          type: string
          description: '`inbox` or `outbox`.'
        from_name:
          type: string
        from_email:
          type: string
        to_name:
          type: string
        to_email:
          type: string
        cc:
          type: array
          items:
            type: string
        bcc:
          type: array
          items:
            type: string
        subject:
          type: string
        replied_to_uuid:
          type: string
          format: uuid
          nullable: true
        bounced_by_uuid:
          type: string
          format: uuid
          nullable: true
        sent_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    email-body:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        team_id:
          type: integer
        body:
          type: string
        attachments:
          type: array
          items:
            type: object
        subject:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    mailbox:
      type: object
      properties:
        uuid:
          type: string
        team_id:
          type: integer
        user_id:
          type: integer
        sender_profile_uuid:
          type: string
        email:
          type: string
          example: outreach@company.com
        sender_name:
          type: string
          example: John from Company
        provider:
          type: string
        status:
          type: string
        automation_daily_limit:
          type: integer
          example: 50
        automation_task_interval:
          type: integer
          example: 120
        custom_tracking_domain_uuid:
          type: string
          nullable: true
        connection_settings:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ai-template:
      type: object
      properties:
        uuid:
          type: string
        team_id:
          type: integer
        user_id:
          type: integer
        name:
          type: string
          example: Personalized Intro
        prompt:
          type: string
          nullable: true
        body:
          type: string
          nullable: true
        subject:
          type: string
          nullable: true
        fallback_body:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        enable_validation:
          type: boolean
        template_category_uuid:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    mixed-filter-type:
      description: >
        Flexible filter value. Supports: scalar (equals), array (IN), object
        with operator, `"is_null"`, `"is_not_null"`.
      oneOf:
        - type: array
          items:
            type: string
        - type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: integer
        - type: string
          enum:
            - is_null
            - is_not_null
        - type: string
        - type: integer
  parameters:
    uuid-path:
      in: path
      name: uuid
      required: true
      schema:
        type: string
      description: Resource UUID.
    flowUuid-path:
      in: path
      name: flowUuid
      required: true
      schema:
        type: string
      description: Automation UUID.
    limit:
      in: query
      name: limit
      required: false
      schema:
        type: integer
        format: int32
        default: 20
        example: 20
      description: Items per page (default 20).
    offset:
      in: query
      name: offset
      required: false
      schema:
        type: integer
        format: int32
        default: 0
        example: 0
      description: Items to skip (default 0).
    order-field:
      in: query
      name: order_field
      required: false
      schema:
        type: string
        default: created_at
        example: created_at
      description: Sort field (default `created_at`).
    order-type:
      in: query
      name: order_type
      required: false
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc
        example: asc
      description: Sort direction.
