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

# List Folder Entities

Lists entities within a folder or at the workspace root. Returns folders, prompts, snippets, workflows, datasets, evaluations, AB tests, and input variable sets.

This endpoint is the primary way to browse the unified registry programmatically — equivalent to viewing the registry page in the PromptLayer dashboard.

## Behavior Notes

When `include_metadata=true`, the `metadata` field contains type-specific information:

| Entity Type                                                    | Metadata Fields                                                                    |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **PROMPT** / **SNIPPET**                                       | `type` (`"chat"` or `"completion"` or `null`), `latest_version_number`             |
| **WORKFLOW**                                                   | `latest_version_number`                                                            |
| **DATASET**                                                    | `isDraft` (boolean — `true` if only draft versions exist), `latest_version_number` |
| **FOLDER**, **REPORT**, **AB\_TEST**, **INPUT\_VARIABLE\_SET** | Empty object `{}`                                                                  |

Sorting behavior:

* Semantic search results are sorted by relevance.
* Text search prioritizes prompts and snippets whose names match before content-only matches.
* When `sort_by` is provided and search ordering does not take precedence, results are sorted by the requested field and `sort_order`.


## OpenAPI

````yaml GET /api/public/v2/folders/entities
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security:
  - ApiKeyAuth: []
paths:
  /api/public/v2/folders/entities:
    get:
      tags:
        - folders
      summary: List Folder Entities
      operationId: list_folder_entities_api_public_v2_folders_entities_get
      parameters:
        - name: workspace_id
          in: query
          required: true
          schema:
            type: integer
            title: Workspace ID
            description: The ID of the workspace to list entities from.
        - name: folder_id
          in: query
          required: false
          schema:
            type: integer
            title: Folder ID
            description: >-
              The ID of the folder to list entities from. If not provided, lists
              entities at the workspace root level.
        - name: filter_type
          in: query
          required: false
          schema:
            oneOf:
              - type: string
                enum:
                  - FOLDER
                  - PROMPT
                  - SNIPPET
                  - WORKFLOW
                  - DATASET
                  - REPORT
                  - AB_TEST
                  - INPUT_VARIABLE_SET
              - type: array
                items:
                  type: string
                  enum:
                    - FOLDER
                    - PROMPT
                    - SNIPPET
                    - WORKFLOW
                    - DATASET
                    - REPORT
                    - AB_TEST
                    - INPUT_VARIABLE_SET
            title: Filter Type
            description: >-
              Filter entities by type. Can be a single type or a list of types.
              If not provided, all entity types are returned.
        - name: search_query
          in: query
          required: false
          schema:
            type: string
            title: Search Query
            description: Search entities by name (case-insensitive partial match).
        - name: flatten
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Flatten
            description: >-
              When true, returns all entities recursively within the folder
              hierarchy instead of only direct children.
        - name: include_metadata
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Include Metadata
            description: >-
              When true, includes type-specific metadata for each entity (e.g.,
              prompt type, latest version number).
        - name: created_by_email
          in: query
          required: false
          schema:
            type: string
          description: Filter by the creator's email address.
        - name: created_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter resources created at or after this timestamp.
        - name: created_before
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter resources created at or before this timestamp.
        - name: updated_after
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter resources updated at or after this timestamp.
        - name: updated_before
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter resources updated at or before this timestamp.
        - name: external_source
          in: query
          required: false
          schema:
            type: string
          description: External ID source to filter by. Must be provided with external_id.
        - name: external_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            External ID value to filter by. Must be provided with
            external_source.
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - created_at
              - updated_at
              - name
              - id
          description: Sort field.
        - name: sort_order
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Sort direction.
        - name: tags
          in: query
          required: false
          schema:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
          description: Filter entities by tags. Applies to entity types that support tags.
        - name: semantic_search
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Use semantic search instead of text matching. Requires search_query.
        - name: semantic_search_top_k
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: Maximum number of semantic search results to consider.
        - name: semantic_search_threshold
          in: query
          required: false
          schema:
            type: number
            exclusiveMinimum: 0
            maximum: 2
          description: Maximum semantic search distance threshold.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFolderEntitiesResponse'
        '400':
          description: Bad request - Missing or invalid workspace_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderNotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    ListFolderEntitiesResponse:
      type: object
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/FolderEntity'
          description: List of entities matching the query.
      title: ListFolderEntitiesResponse
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          default: false
          description: Indicates that the request failed.
        message:
          type: string
          description: Human-readable error message.
        error:
          type: string
          description: Machine-readable or fallback error message.
      additionalProperties: true
      description: >-
        Standard error response. Some legacy endpoints may return either message
        or error.
    FolderNotFoundError:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
      title: FolderNotFoundError
    FolderEntity:
      type: object
      required:
        - id
        - name
        - type
        - path
      properties:
        id:
          type: integer
          description: Unique identifier for the entity
        name:
          type: string
          description: Name of the entity
        type:
          $ref: '#/components/schemas/EntityType'
        created_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the entity was created
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the entity was last updated
        folder_id:
          type: integer
          nullable: true
          description: >-
            ID of the folder containing this entity. Null for root-level
            entities.
        path:
          type: array
          items:
            type: string
          description: >-
            Array of folder names representing the entity's location in the
            folder hierarchy.
        metadata:
          nullable: true
          description: Type-specific metadata. Included only when include_metadata=true.
          oneOf:
            - $ref: '#/components/schemas/PromptEntityMetadata'
            - $ref: '#/components/schemas/WorkflowEntityMetadata'
            - $ref: '#/components/schemas/DatasetEntityMetadata'
            - type: object
        external_ids:
          type: array
          items:
            $ref: '#/components/schemas/ExternalId'
          description: External ID mappings attached to this entity.
      title: FolderEntity
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EntityType:
      type: string
      enum:
        - FOLDER
        - PROMPT
        - SNIPPET
        - WORKFLOW
        - DATASET
        - REPORT
        - AB_TEST
        - INPUT_VARIABLE_SET
      description: >-
        The type of entity. SNIPPET is a pseudo-entity type representing
        completion-type prompts.
    PromptEntityMetadata:
      type: object
      properties:
        type:
          type: string
          nullable: true
          enum:
            - chat
            - completion
          description: The prompt template type.
        latest_version_number:
          type: integer
          nullable: true
          description: The latest version number of the prompt.
      title: PromptEntityMetadata
    WorkflowEntityMetadata:
      type: object
      properties:
        latest_version_number:
          type: integer
          nullable: true
          description: The latest version number of the workflow.
      title: WorkflowEntityMetadata
    DatasetEntityMetadata:
      type: object
      properties:
        isDraft:
          type: boolean
          description: >-
            Whether the dataset group only has draft versions (no published
            versions).
        latest_version_number:
          type: integer
          nullable: true
          description: The latest published version number of the dataset.
      title: DatasetEntityMetadata
    ExternalId:
      properties:
        source:
          type: string
          maxLength: 128
          minLength: 1
          title: Source
          description: The external system or namespace that owns the ID.
        external_id:
          type: string
          maxLength: 512
          minLength: 1
          title: External Id
          description: The identifier for this entity in the external system.
      type: object
      required:
        - source
        - external_id
      additionalProperties: false
      title: ExternalId
      description: >-
        Customer-defined mapping between a PromptLayer entity and an external
        system identifier.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  responses:
    UnauthorizedError:
      description: Unauthorized - missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Validation error - request parameters or body are invalid.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/HTTPValidationError'
              - $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````