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: <x-api-key>'
{
  "entities": [
    {
      "id": 123,
      "name": "<string>",
      "type": "FOLDER",
      "path": [
        "<string>"
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "folder_id": 123,
      "metadata": {
        "type": "chat",
        "latest_version_number": 123
      }
    }
  ]
}
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.

​
Query Parameters

​
Browsing

​
folder_id
integer
The folder to list entities from. If omitted, returns entities at the workspace root.
​
flatten
boolean
default:"false"
When true, returns all entities recursively from the target folder and all of its subfolders. When false (default), only returns direct children of the folder (or root).
​
filter_type
string | string[]
Restrict results to one or more entity types. Accepts a single value or a list. Valid values:FOLDER, PROMPT, SNIPPET, WORKFLOW, DATASET, REPORT, AB_TEST, INPUT_VARIABLE_SETIf omitted, all entity types are returned.
​
include_metadata
boolean
default:"false"
When true, each entity includes a metadata object with type-specific information. See Entity Metadata below.
​
tags
string[]
Filter entities by tags. Only entities that contain all specified tags are returned. Applies to prompts, workflows, datasets, and evaluations. Folders, AB tests, and input variable sets are excluded when this filter is active.
​
search_query
string
Filter entities by name using case-insensitive partial matching. For prompts, this also searches across prompt version content.
​
semantic_search
boolean
default:"false"
Enable semantic (vector) search instead of text matching. Requires search_query to be set. Currently supports prompts and folders.
​
semantic_search_top_k
integer
default:"100"
Maximum number of results to return from semantic search. Range: 1 – 500.
​
semantic_search_threshold
number
Maximum distance threshold for semantic search results. Only results within this distance are returned. Range: (0, 2]. If omitted, no threshold is applied.

​
Response

Returns an object with a single entities array. Each entity has the following shape:
​
entities
Entity[]

​
Entity Metadata

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 (distance ascending).
  • Text search: Prompts and snippets with a name match are prioritized above content-only matches.
  • No search: Results are returned in default database order.

​
Examples

​
List all entities at the workspace root

curl -X GET "https://api.promptlayer.com/api/public/v2/folders/entities" \
  -H "X-API-KEY: your_api_key"

​
Browse inside a folder

curl -X GET "https://api.promptlayer.com/api/public/v2/folders/entities?folder_id=42" \
  -H "X-API-KEY: your_api_key"

​
List only prompts and workflows, with metadata

curl -X GET "https://api.promptlayer.com/api/public/v2/folders/entities?filter_type=PROMPT&filter_type=WORKFLOW&include_metadata=true" \
  -H "X-API-KEY: your_api_key"

​
Search across all folders (flattened)

curl -X GET "https://api.promptlayer.com/api/public/v2/folders/entities?search_query=summarize&flatten=true" \
  -H "X-API-KEY: your_api_key"

​
Semantic search with threshold

curl -X GET "https://api.promptlayer.com/api/public/v2/folders/entities?search_query=customer+onboarding&semantic_search=true&semantic_search_threshold=1.0" \
  -H "X-API-KEY: your_api_key"

​
Filter by tags

curl -X GET "https://api.promptlayer.com/api/public/v2/folders/entities?tags=production&tags=v2&flatten=true" \
  -H "X-API-KEY: your_api_key"

​
Example Response

{
  "entities": [
    {
      "id": 10,
      "name": "Prompts",
      "type": "FOLDER",
      "created_at": "2025-01-10T08:00:00",
      "updated_at": "2025-02-15T12:30:00",
      "folder_id": null,
      "path": ["Prompts"],
      "metadata": null,
      "distance": null,
      "created_by_email": null
    },
    {
      "id": 205,
      "name": "summarize-article",
      "type": "PROMPT",
      "created_at": "2025-02-01T14:20:00",
      "updated_at": "2025-03-10T09:15:00",
      "folder_id": null,
      "path": [],
      "metadata": {
        "type": "chat",
        "latest_version_number": 5
      },
      "distance": null,
      "created_by_email": "alice@example.com"
    },
    {
      "id": 88,
      "name": "onboarding-flow",
      "type": "WORKFLOW",
      "created_at": "2025-01-20T11:00:00",
      "updated_at": "2025-03-01T16:45:00",
      "folder_id": null,
      "path": [],
      "metadata": {
        "latest_version_number": 3
      },
      "distance": null,
      "created_by_email": "bob@example.com"
    }
  ]
}

Headers

​
X-API-KEY
string
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).

Response

Successful Response

​
entities
FolderEntity · object[]

List of entities matching the query.