Getting Started

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

Go to Settings -> API Keys
Click “Create API Key”
Choose your key type and project (for project-level keys)
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/auth/validate" \
  -H "X-API-Key: your-project-api-key"

Using Organization-Level Keys

curl -X GET "https://server.promptwatch.com/api/v2/auth/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/auth/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"

One-step project setup

Use an organization-level key to create a project, enrich it from the website, and generate monitors with prompts in one call. This is synchronous and can take 1-2 minutes. Omit monitors to create one monitor with 10 mixed prompts.

curl -X POST "https://server.promptwatch.com/api/v2/projects/setup" \
  -H "X-API-Key: your-org-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme",
    "website": "https://acme.com",
    "countryCode": "US",
    "languageCode": "en",
    "monitors": [
      { "prompts": 10 },
      { "prompts": 10, "type": "COMPETITOR_COMPARISON" }
    ]
  }'

At most 3 monitors and 50 prompts in total. For more control, use POST /projects and POST /monitors separately. If prompt generation or the monitor write fails after the project is created, the response is still 201 with monitors: [] and a warning. Use the returned project id with POST /monitors instead of calling setup again — the project already counts toward the org’s project limit.

Error Handling

The API uses standard HTTP status codes:

Status Code	Meaning
200	Success
400	Bad Request - Check your parameters
401	Unauthorized - Invalid API key
403	Forbidden - Missing Project ID or insufficient permissions
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Server 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?

Email: team@promptwatch.com
Website: promptwatch.com

Overview

API Reference

Changelog

Prerequisites

Step 1: Get Your API Key

API Key Types

Creating an API Key

Step 2: Authenticate Your Requests

Using Project-Level Keys

Using Organization-Level Keys

Step 3: Validate Your API Key

Step 4: Make Your First API Request

One-step project setup

Error Handling

Next Steps

API Reference

Rate Limits

Need Help?

​Prerequisites

​Step 1: Get Your API Key

​API Key Types

​Creating an API Key

​Step 2: Authenticate Your Requests

​Using Project-Level Keys

​Using Organization-Level Keys

​Step 3: Validate Your API Key

​Step 4: Make Your First API Request

​One-step project setup

​Error Handling

​Next Steps

API Reference

Rate Limits

​Need Help?

Prerequisites

Step 1: Get Your API Key

API Key Types

Creating an API Key

Step 2: Authenticate Your Requests

Using Project-Level Keys

Using Organization-Level Keys

Step 3: Validate Your API Key

Step 4: Make Your First API Request

One-step project setup

Error Handling

Next Steps

Need Help?