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

# List Organization Folders

> List DialNexa organization folders with search and pagination so integrations can resolve folder IDs before reading or organizing agents.

Read only

List organization folders to resolve the folder IDs and names available in the authenticated workspace. The operation returns active folders only and sorts them from oldest to newest.

## When to list organization folders

* Resolve a folder ID before filtering or organizing agents.
* Build a folder picker without hard-coding workspace-specific IDs.
* Confirm that a folder exists before reading its details.

## Query parameters

| Parameter | Description |
| - | - |
| `search` | Optional case-insensitive folder name search. |
| `page` | Page number as a whole number, starting from 1. Defaults to 1. |
| `limit` | Results per page as a whole number from 1 to 50. Defaults to 20. |
| `export` | Accepted for compatibility with other list endpoints, but this endpoint always paginates: `export` has no effect here. Default: `false`. |

## Verify the result

Use the `folders` array to read each folder's `id` and `name`. Each folder also carries `organization_id`, `is_deleted`, `createdAt`, `updatedAt`, an `organization` object with `id` and `title`, and `agentCount`, the number of agents in the folder that are not deleted. `agentCount` is returned by this list only, not by [Get Organization Folder](https://dialnexa.com/docs/api-reference/v1/organization-folders/get.md). The response also includes the applied `page` and `limit` values; results are always paginated, so request further pages until one comes back short. An empty `folders` array means no active folder matched the request.

## Errors and recovery

* `401 Unauthorized` means the API key is missing or invalid.
* `404 Not Found` means the authenticated organization no longer exists.
* `400 Bad Request` means `page` or `limit` does not start with a number or is outside the supported range (a value such as `2.5` or `5abc` is read as its leading whole number), for example `Limit must be between 1 and 50`. Correct the query before retrying.

## Related endpoints

* [Get Organization Folder](https://dialnexa.com/docs/api-reference/v1/organization-folders/get.md): read one folder by ID.
* [List Agents](https://dialnexa.com/docs/api-reference/v1/agents/list.md): list the agents that can be organized into folders.
* [Agent folders](https://dialnexa.com/docs/agents/agent-folders.md): organize agents in the dashboard.


## OpenAPI

````yaml GET /v1/organization-folders
openapi: 3.0.0
info:
  title: DialNexa API
  description: Public `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: Agents
  - name: Batch Calls
  - name: Calls
  - name: Knowledge Base
  - name: Languages
  - name: LLMs
  - name: Phone Numbers
  - name: Organization Folders
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
  - name: Authentication
  - name: Agent Builder
  - name: Agent Evaluations
paths:
  /v1/organization-folders:
    get:
      tags:
        - Organization Folders
      summary: List Organization Folders
      description: >-
        Returns active folders for the authenticated organization with optional
        search and pagination.
      operationId: listOrganizationFolders
      parameters:
        - name: search
          required: false
          in: query
          description: Search by folder name
          schema:
            example: Call
            type: string
        - name: page
          required: false
          in: query
          description: >-
            Page number, starting from 1. Default 1. Read with parseInt, so 2.5
            or 2abc is page 2; a value that does not start with a number, or is
            below 1, returns 400.
          schema:
            default: '1'
            example: '1'
            type: string
        - name: limit
          required: false
          in: query
          description: >-
            Folders per page, from 1 to 50. Default 20. Read with parseInt, so
            10.5 is 10; a value that does not start with a number, or is outside
            1 to 50, returns 400.
          schema:
            default: '20'
            example: '20'
            type: string
        - name: export
          required: false
          in: query
          description: >-
            Accepted for compatibility but ignored: results are always
            paginated.
          schema:
            default: false
            example: true
            type: boolean
      responses:
        '200':
          description: Organization folders returned successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - error
                  - statusCode
                  - message
                  - data
                  - timestamp
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  error:
                    type: boolean
                    enum:
                      - false
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    required:
                      - folders
                      - page
                      - limit
                    properties:
                      folders:
                        type: array
                        items:
                          allOf:
                            - $ref: '#/components/schemas/OrganizationFolder'
                            - type: object
                              required:
                                - agentCount
                              properties:
                                agentCount:
                                  type: integer
                                  example: 3
                                  description: >-
                                    Number of agents in the folder that are not
                                    deleted. Returned by the list only, not by
                                    Get Organization Folder.
                      page:
                        type: integer
                        example: 1
                      limit:
                        type: integer
                        example: 20
                  timestamp:
                    type: string
                    format: date-time
              examples:
                success:
                  summary: Successful response
                  value:
                    success: true
                    error: false
                    statusCode: 200
                    message: Success
                    data:
                      folders:
                        - id: f5k2m8x1q9w3zp
                          organization_id: o14XKPP84rt22g
                          name: Sales Agents
                          is_deleted: false
                          createdAt: '2026-07-03T10:30:00.000Z'
                          updatedAt: '2026-07-03T10:30:00.000Z'
                          organization:
                            id: o14XKPP84rt22g
                            title: Acme Lending
                          agentCount: 3
                      page: 1
                      limit: 20
                    timestamp: '2026-09-07T06:00:00.000Z'
        '400':
          description: page or limit is out of range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    error: true
                    success: false
                    data: []
                    message: Limit must be between 1 and 50
                    errors: []
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    error: true
                    success: false
                    data: []
                    message: Invalid API key
                    errors: []
        '404':
          description: Authenticated organization not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    statusCode: 404
                    error: true
                    success: false
                    data: []
                    message: Organization with ID o14XKPP84rt22g not found
                    errors: []
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    error: true
                    success: false
                    data: []
                    message: Internal server error
                    errors: []
      security:
        - bearer: []
components:
  schemas:
    OrganizationFolder:
      type: object
      properties:
        id:
          type: string
          example: f5k2m8x1q9w3zp
        organization_id:
          type: string
          example: o14XKPP84rt22g
        name:
          type: string
          maxLength: 35
          example: Sales Agents
        is_deleted:
          type: boolean
          example: false
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        organization:
          type: object
          description: The organization that owns the folder.
          properties:
            id:
              type: string
              example: o14XKPP84rt22g
            title:
              type: string
              example: Acme Lending
      required:
        - id
        - organization_id
        - name
        - is_deleted
        - createdAt
        - updatedAt
    ErrorResponse:
      type: object
      description: Error body on endpoints without response filtering.
      properties:
        statusCode:
          type: integer
          example: 404
        error:
          type: boolean
          enum:
            - true
        success:
          type: boolean
          enum:
            - false
        data:
          oneOf:
            - type: object
              properties:
                code:
                  type: string
                  description: Machine-readable refusal code.
            - type: array
              items: {}
          description: >-
            For a coded refusal, an object with code and the details listed for
            that code. Otherwise an empty array.
        message:
          type: string
        errors:
          type: array
          items:
            type: string
          description: Validation messages for a 400. Empty for other errors.
        validation_errors:
          type: array
          description: >-
            Present when uploaded rows fail number validation (batch and
            workflow lead uploads): one group per distinct error.
          items:
            type: object
            properties:
              error:
                type: string
              rows:
                type: array
                items:
                  type: integer
                description: Row numbers with this error.
              phone_numbers:
                type: array
                items:
                  type: string
        invalid_row_count:
          type: integer
          description: 'Present with validation_errors: how many rows failed.'
      required:
        - statusCode
        - error
        - success
        - data
        - message
        - errors
  securitySchemes:
    bearer:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.