> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enginy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a list

> Create a new empty destination list for contacts or companies. For a user request like "build/find me a new list of prospects", create the destination list, then use AI Finder preview and import tools to populate it instead of returning existing CRM contacts.

Responses include direct Enginy app URLs when available. The created list response includes an `appUrl` field. MCP agents should return those URLs to users whenever they are present in the response.

    > **Required scope:** `LISTS_WRITE`
    >
    > **Rate limit:** 30 requests per minute



## OpenAPI

````yaml https://openapi.enginy.ai/definitions.json post /v1/lists
openapi: 3.1.0
info:
  title: Enginy API
  version: 1.0.0
  description: Public API for Enginy platform
servers:
  - url: https://openapi.enginy.ai
    description: Configured server
security: []
tags:
  - name: AI Variables
    description: >-
      Manage AI variables and discover the entity fields you can reference in
      prompts and entity requests.
  - name: Inbox
    description: >-
      Inbox endpoints for listing contact threads, reading thread messages,
      managing tags, and sending manual replies.
  - name: Workflows
    description: >-
      Build, validate, publish, run, and inspect advanced (graph) workflows,
      plus the block/condition catalog needed to author a workflow plan.
paths:
  /v1/lists:
    post:
      tags:
        - Lists
      summary: Create a list
      description: >-
        Create a new empty destination list for contacts or companies. For a
        user request like "build/find me a new list of prospects", create the
        destination list, then use AI Finder preview and import tools to
        populate it instead of returning existing CRM contacts.


        Responses include direct Enginy app URLs when available. The created
        list response includes an `appUrl` field. MCP agents should return those
        URLs to users whenever they are present in the response.

            > **Required scope:** `LISTS_WRITE`
            >
            > **Rate limit:** 30 requests per minute
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - CONTACTS
                    - COMPANIES
                  description: Type of list to create (CONTACTS or COMPANIES).
                name:
                  type: string
                  minLength: 1
                  description: Name of the list
                description:
                  type:
                    - string
                    - 'null'
                  description: Description of the list
                folderId:
                  type:
                    - integer
                    - 'null'
                  exclusiveMinimum: 0
                  description: Folder ID to place the list in
              required:
                - type
                - name
      responses:
        '201':
          description: List created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: number
                        description: Unique identifier for the list
                      name:
                        type: string
                        description: Name of the list
                      description:
                        type:
                          - string
                          - 'null'
                        description: Description of the list
                      type:
                        type: string
                        enum:
                          - CONTACTS
                          - COMPANIES
                        description: Type of the list (CONTACTS or COMPANIES)
                      appUrl:
                        type: string
                        format: uri
                        description: Direct Enginy app URL for opening this list.
                      entitiesCount:
                        type: number
                        description: Number of entities in the list
                      createdBy:
                        type: object
                        properties:
                          id:
                            type: number
                            description: ID of the user who created the list
                          name:
                            type:
                              - string
                              - 'null'
                            description: Name of the user who created the list
                        required:
                          - id
                          - name
                        description: User who created the list
                      createdAt:
                        type: string
                        format: date-time
                        description: Date and time when the list was created
                    required:
                      - id
                      - name
                      - description
                      - type
                      - appUrl
                      - entitiesCount
                      - createdBy
                      - createdAt
                required:
                  - status
                  - message
                  - data
        '400':
          description: Bad request - validation error or folder not found
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````