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

# Introduction

> Guide to the Targeter REST API

## Welcome to the Targeter API

The Targeter REST API is the partner-facing HTTP API for Targeter: obtain a JWT and create or resolve campaigns from external systems. As an approved partner with issued API credentials, you can integrate on behalf of your clients.

Current REST API version: **1.2.0**.

## Base URL

All API requests are made to the base URL provided with your credentials:

```
https://app.targeter.tech/api
```

Some clients use a tenant-specific host (e.g. `https://{client_slug}.targeter.tech/api`). Use the base URL you received from Targeter.

## Partner Authentication

The Targeter API uses JWT (JSON Web Token) authentication for trusted third-party partners. Protected routes expect `Authorization: Bearer <token>` (obtain the token from `POST /auth/token`). Here's how it works:

1. **Receive Issued Credentials**: Get your API key and plain-text secret issued by the Targeter team for your approved partnership
2. **Exchange for Token**: Use your issued credentials to get a JWT from `/auth/token` (tokens expire after one hour)
3. **Include in Requests**: Add the token to the `Authorization` header for protected routes

### Example Partner Authentication Flow

```bash theme={null}
# Step 1: Get JWT token using your issued credentials
curl -X POST "https://app.targeter.tech/api/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_ISSUED_PARTNER_KEY",
    "api_secret": "YOUR_ISSUED_PARTNER_SECRET"
  }'

# Step 2: Use token in API calls on behalf of your clients
curl -X POST "https://app.targeter.tech/api/campaign" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "material": ["https://example.com/image.jpg"],
      "name": "Example Campaign",
      "reference_id": "REF-001",
      "target_url": "https://example.com/listing/001"
    }
  }'
```

## Rate Limits

Not yet implemented.

## Error Handling

The API uses standard HTTP status codes and returns detailed error information:

```json theme={null}
{
    "error": "Missing required field: source.reference_id: Reference ID is required"
}
```

Validation errors on authentication may include a `details` array:

```json theme={null}
{
    "error": "Invalid request payload",
    "details": [
        {
            "path": ["api_key"],
            "message": "Invalid input: expected string, received undefined"
        }
    ]
}
```