> ## Documentation Index
> Fetch the complete documentation index at: https://promptwatch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Learn how to authenticate and make your first API request

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](https://app.promptwatch.com))
* 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

<Warning>
  Store your API key securely. Never commit it to version control or share it publicly.
</Warning>

## Step 2: Authenticate Your Requests

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

### Using Project-Level Keys

```bash theme={null}
curl -X GET "https://server.promptwatch.com/api/v2/validate" \
  -H "X-API-Key: your-project-api-key"
```

### Using Organization-Level Keys

```bash theme={null}
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 <a href="/docs/public/assets/promptwatch-api.postman_collection.json" download="promptwatch-api.postman_collection.json">Postman Collection</a> for pre-configured requests with all endpoints.

## Step 3: Validate Your API Key

Test your API key by calling the validate endpoint:

```bash theme={null}
curl -X GET "https://server.promptwatch.com/api/v2/validate" \
  -H "X-API-Key: your-api-key"
```

**Success Response:**

```json theme={null}
{
  "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:

```bash theme={null}
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 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:**

```json theme={null}
{
  "error": "UNAUTHORIZED",
  "message": "Invalid API key"
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/v2/introduction">
    Explore all available endpoints
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/rate-limits">
    Learn about rate limits
  </Card>
</CardGroup>

## Need Help?

* **Email**: [team@promptwatch.com](mailto:team@promptwatch.com)
* **Website**: [promptwatch.com](https://promptwatch.com)