Skip to main content
This guide will help you get started with the Promptwatch API, from authentication to making your first request.

​
Prerequisites

  • A Promptwatch account (Sign up here)
  • An active project
  • Basic familiarity with RESTful APIs

​
Step 1: Get Your API Key

​
API Key Types

Promptwatch offers two types of API keys: Project-Level Keys
  • Scoped to a specific project
  • Automatically associated with the project
  • Recommended for most use cases
Organization-Level Keys
  • Access to all projects in your organization
  • Require X-Project-Id header to specify which project to query
  • Useful for cross-project analytics

​
Creating an API Key

  1. Go to Settings -> API Keys
  2. Click “Create API Key”
  3. Choose your key type and project (for project-level keys)
  4. Copy and securely store your API key
Store your API key securely. Never commit it to version control or share it publicly.

​
Step 2: Authenticate Your Requests

All API requests require authentication via the X-API-Key header.

​
Using Project-Level Keys

curl -X GET "https://server.promptwatch.com/api/v2/validate" \
  -H "X-API-Key: your-project-api-key"

​
Using Organization-Level Keys

curl -X GET "https://server.promptwatch.com/api/v2/validate" \
  -H "X-API-Key: your-org-api-key" \
  -H "X-Project-Id: your-project-id"
Postman: Download our Postman Collection for pre-configured requests with all endpoints.

​
Step 3: Validate Your API Key

Test your API key by calling the validate endpoint: 
curl -X GET "https://server.promptwatch.com/api/v2/validate" \
  -H "X-API-Key: your-api-key"
Success Response: 
{
  "valid": true,
  "keyType": "project",
  "project": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Project",
    "slug": "my-project"
  },
  "organization": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "My Company",
    "slug": "my-company"
  },
  "apiKey": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "name": "Production Key",
    "createdAt": "2025-01-01T00:00:00Z",
    "lastUsedAt": "2026-01-15T10:30:00Z"
  }
}

​
Step 4: Make Your First API Request

Now that your API key is validated, try fetching your monitors: 
curl -X GET "https://server.promptwatch.com/api/v2/monitors" \
  -H "X-API-Key: your-api-key"

​
Error Handling

The API uses standard HTTP status codes:
Status CodeMeaning
200Success
400Bad Request - Check your parameters
401Unauthorized - Invalid API key
403Forbidden - Missing Project ID or insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Server Error - Contact support
Error Response Format: 
{
  "error": "UNAUTHORIZED",
  "message": "Invalid API key"
}

​
Next Steps

API Reference

Explore all available endpoints

Rate Limits

Learn about rate limits

​
Need Help?