Prompts API

The Prompts API allows you to create and manage reusable prompt templates for consistent AI interactions. Use templates to standardize your prompts across different use cases and ensure consistent outputs.

Required Headers

All API endpoints require these headers:

Name
Authorization
Type
string
Description
Bearer token for authentication. Format: 'Bearer your-token-here'
Name
traceparent
Type
string
Description
OpenTelemetry trace parent for distributed tracing
Name
tracestate
Type
string
Description
OpenTelemetry trace state information

GET/v1/management/prompts

List Prompts

List all prompt templates in your organization. Results are paginated and can be filtered.

Query Parameters

Name
page
Type
integer
Description
Page number for pagination. Defaults to 1
Name
pageSize
Type
integer
Description
Number of items per page. Defaults to 10

Response Properties

Name
items
Type
array
Description
Array of prompt templates
- Name
  id
  Type
  string
  Description
  Unique identifier for the prompt template
- Name
  name
  Type
  string
  Description
  Display name of the template
- Name
  description
  Type
  string
  Description
  Detailed description of the template's purpose
- Name
  created
  Type
  string
  Description
  Creation timestamp
- Name
  updated
  Type
  string
  Description
  Last update timestamp
- Name
  versions
  Type
  array
  Description
  Array of template versions
  Name
  id
  Type
  string
  Description
  Version identifier
  Name
  name
  Type
  string
  Description
  Version name
  Name
  template
  Type
  string
  Description
  The prompt template text
  Name
  variables
  Type
  object
  Description
  Variable definitions and constraints
  Name
  labels
  Type
  array
  Description
  Tags for categorizing the template
  Name
  created
  Type
  string
  Description
  Version creation timestamp
  Name
  isActive
  Type
  boolean
  Description
  Whether this is the active version
Name
page
Type
integer
Description
Current page number
Name
pageSize
Type
integer
Description
Items per page
Name
totalCount
Type
integer
Description
Total number of templates

Request

GET

/v1/management/prompts

curl -X GET https://api.usageguard.com/v1/management/prompts?page=1&pageSize=10 \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}"

Response

{
  "items": [
    {
      "id": "prompt_abc123",
      "name": "Translation Template",
      "description": "Translates text between languages",
      "created": "2024-03-15T10:30:00Z",
      "updated": "2024-03-15T10:30:00Z",
      "versions": [
        {
          "id": "ver_xyz789",
          "name": "v1.0",
          "template": "Translate the following {{source_language}} text to {{target_language}}: {{text}}",
          "variables": {
            "source_language": {
              "type": "string",
              "required": true
            },
            "target_language": {
              "type": "string",
              "required": true
            },
            "text": {
              "type": "string",
              "required": true
            }
          },
          "labels": ["translation", "multilingual"],
          "created": "2024-03-15T10:30:00Z",
          "isActive": true
        }
      ]
    }
  ],
  "page": 1,
  "pageSize": 10,
  "totalCount": 1
}

401: Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

403: Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

POST/v1/management/prompts

Create Prompt

Create a new prompt template with an initial version.

Request Body

Name
name
Type
string
Description
Display name for the template
Name
description
Type
string
Description
Detailed description of the template's purpose
Name
template
Type
string
Description
The prompt template text with variable placeholders
Name
variables
Type
object
Description
Definitions and constraints for template variables
Name
labels
Type
array
Description
Tags for categorizing the template

Request

POST

/v1/management/prompts

curl -X POST https://api.usageguard.com/v1/management/prompts \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Translation Template",
    "description": "Translates text between languages",
    "template": "Translate the following {{source_language}} text to {{target_language}}: {{text}}",
    "variables": {
      "source_language": {
        "type": "string",
        "required": true
      },
      "target_language": {
        "type": "string",
        "required": true
      },
      "text": {
        "type": "string",
        "required": true
      }
    },
    "labels": ["translation", "multilingual"]
  }'

Response

{
  "id": "prompt_abc123",
  "name": "Translation Template",
  "description": "Translates text between languages",
  "created": "2024-03-15T10:30:00Z",
  "updated": "2024-03-15T10:30:00Z",
  "versions": [
    {
      "id": "ver_xyz789",
      "name": "v1.0",
      "template": "Translate the following {{source_language}} text to {{target_language}}: {{text}}",
      "variables": {
        "source_language": {
          "type": "string",
          "required": true
        },
        "target_language": {
          "type": "string",
          "required": true
        },
        "text": {
          "type": "string",
          "required": true
        }
      },
      "labels": ["translation", "multilingual"],
      "created": "2024-03-15T10:30:00Z",
      "isActive": true
    }
  ]
}

GET/v1/management/prompts/{promptId}

Get Prompt

Retrieve a specific prompt template and all its versions.

Path Parameters

Name
promptId
Type
string
Description
The unique identifier of the prompt template

Request

GET

/v1/management/prompts/{promptId}

curl -X GET https://api.usageguard.com/v1/management/prompts/prompt_abc123 \
  -H "Authorization: Bearer {token}" \
  -H "traceparent: {traceparent}" \
  -H "tracestate: {tracestate}"

Response

{
  "id": "prompt_abc123",
  "name": "Translation Template",
  "description": "Translates text between languages",
  "created": "2024-03-15T10:30:00Z",
  "updated": "2024-03-15T10:30:00Z",
  "versions": [
    {
      "id": "ver_xyz789",
      "name": "v1.0",
      "template": "Translate the following {{source_language}} text to {{target_language}}: {{text}}",
      "variables": {
        "source_language": {
          "type": "string",
          "required": true
        },
        "target_language": {
          "type": "string",
          "required": true
        },
        "text": {
          "type": "string",
          "required": true
        }
      },
      "labels": ["translation", "multilingual"],
      "created": "2024-03-15T10:30:00Z",
      "isActive": true
    }
  ]
}

404: Not Found

{
  "error": "Not Found",
  "message": "Prompt template not found"
}