Query Prompts

List and filter prompts in your organization

Endpoint

method · string · default: "POST"

POST

endpoint · string

/v1/prompt/query

Authentication

This endpoint requires API key authentication. Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

Request Body

filter · object · required

Filter criteria for prompts. Can be “all” for no filtering, or an object with prompt_v2 filters:

• id: Filter by prompt ID
• user_defined_id: Filter by user-defined ID

Each filter supports operators like equals, like, ilike, contains, etc.

Response

data · array

Array of prompt objects

id · string

Unique identifier for the prompt

user_defined_id · string

User-defined identifier

description · string

Prompt description

pretty_name · string

Display name for the prompt

created_at · string

Prompt creation timestamp

major_version · number

Current major version number

metadata · object

Additional metadata

error · string | null

Error message if the request failed, null otherwise

Example Request - Get All Prompts

curl -X POST https://api.helicone.ai/v1/prompt/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": "all"
  }'

Example Request - Filter by User-Defined ID

curl -X POST https://api.helicone.ai/v1/prompt/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "prompt_v2": {
        "user_defined_id": {
          "equals": "customer-support-v1"
        }
      }
    }
  }'

Example Response

{
  "data": [
    {
      "id": "prompt_abc123",
      "user_defined_id": "customer-support-v1",
      "description": "Customer support prompt template",
      "pretty_name": "Customer Support",
      "created_at": "2024-01-01T10:00:00Z",
      "major_version": 2,
      "metadata": {
        "department": "support"
      }
    },
    {
      "id": "prompt_def456",
      "user_defined_id": "sales-assistant",
      "description": "Sales assistant prompt",
      "pretty_name": "Sales Assistant",
      "created_at": "2024-01-05T14:30:00Z",
      "major_version": 1,
      "metadata": {
        "department": "sales"
      }
    }
  ],
  "error": null
}

Filter Operators

The following operators are available for text filters:

• equals: Exact match
• not-equals: Does not match
• like: SQL LIKE pattern matching (case-sensitive)
• ilike: SQL LIKE pattern matching (case-insensitive)
• contains: Contains substring
• not-contains: Does not contain substring