Skip to main content
GET
/
api
/
public
/
v2
/
folders
/
entities
List Folder Entities
curl --request GET \
  --url https://api.promptlayer.com/api/public/v2/folders/entities \
  --header 'X-API-KEY: <api-key>'
{
  "entities": [
    {
      "id": 123,
      "name": "<string>",
      "path": [
        "<string>"
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "folder_id": 123,
      "metadata": {
        "latest_version_number": 123
      },
      "external_ids": [
        {
          "source": "<string>",
          "external_id": "<string>"
        }
      ]
    }
  ]
}

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.

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 TypeMetadata Fields
PROMPT / SNIPPETtype ("chat" or "completion" or null), latest_version_number
WORKFLOWlatest_version_number
DATASETisDraft (boolean — true if only draft versions exist), latest_version_number
FOLDER, REPORT, AB_TEST, INPUT_VARIABLE_SETEmpty 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.

Authorizations

​
X-API-KEY
string
header
required

Query Parameters

​
workspace_id
integer
required

The ID of the workspace to list entities from.

​
folder_id
integer

The ID of the folder to list entities from. If not provided, lists entities at the workspace root level.

​
filter_type

Filter entities by type. Can be a single type or a list of types. If not provided, all entity types are returned.

Available options:
FOLDER,
PROMPT,
SNIPPET,
WORKFLOW,
DATASET,
REPORT,
AB_TEST,
INPUT_VARIABLE_SET
​
search_query
string

Search entities by name (case-insensitive partial match).

​
flatten
boolean
default:false

When true, returns all entities recursively within the folder hierarchy instead of only direct children.

​
include_metadata
boolean
default:false

When true, includes type-specific metadata for each entity (e.g., prompt type, latest version number).

​
created_by_email
string

Filter by the creator's email address.

​
created_after
string<date-time>

Filter resources created at or after this timestamp.

​
created_before
string<date-time>

Filter resources created at or before this timestamp.

​
updated_after
string<date-time>

Filter resources updated at or after this timestamp.

​
updated_before
string<date-time>

Filter resources updated at or before this timestamp.

​
external_source
string

External ID source to filter by. Must be provided with external_id.

​
external_id
string

External ID value to filter by. Must be provided with external_source.

​
sort_by
enum<string>

Sort field.

Available options:
created_at,
updated_at,
name,
id
​
sort_order
enum<string>
default:desc

Sort direction.

Available options:
asc,
desc
​
tags

Filter entities by tags. Applies to entity types that support tags.

​
semantic_search
boolean
default:false

Use semantic search instead of text matching. Requires search_query.

​
semantic_search_top_k
integer
default:100

Maximum number of semantic search results to consider.

Required range: 1 <= x <= 500
​
semantic_search_threshold
number

Maximum semantic search distance threshold.

Required range: x <= 2

Response

Successful Response

​
entities
FolderEntity · object[]

List of entities matching the query.