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

# Management API overview

> Programmatic access to advertiser reporting and campaign management.

The Management API is a REST service for **reporting** and **campaign operations**.
It is connected directly to the Adgentek database and is separate from the
publisher ad-serving API ([REST API integration](/publishers/integrations/rest-api))
used to request ads at runtime.

Use this API when you need to read campaign performance, create or update
campaigns and line items, or automate workflows outside the dashboard.

## Base URL

Production:

```
https://api.adgentek.ai/webapi
```

All versioned routes live under `/v1/...`. Unversioned metadata routes
(`/health`, `/version`, `/openapi.yaml`) sit at the service root.

## Authentication

Send your advertiser API key on every request:

```
x-api-key: adv_YOUR_KEY
```

Keys are org-scoped. Results include only data for the organization attached
to the key.

Each endpoint also requires a **permission** on the key:

| Permission  | Access                                              |
| ----------- | --------------------------------------------------- |
| `reporting` | Read campaign performance rollups                   |
| `campaigns` | Create, update, and manage campaigns and line items |

A key without the required permission returns `403 forbidden`.

## Response format

Successful responses wrap payloads in a `data` field. Errors
use `application/problem+json`:

```json theme={null}
{
  "status": 403,
  "code": "forbidden",
  "message": "user_id must belong to your organization"
}
```

Every response includes version headers:

| Header              | Meaning                           |
| ------------------- | --------------------------------- |
| `X-API-Version`     | Contract version (currently `v1`) |
| `X-Service-Version` | Deployed build identifier         |

## What you can do today

### Campaign management

Write endpoints under `/v1/advertiser/campaigns` and `/v1/advertiser/line-items`
support the full campaign lifecycle: create, validate, compose (campaign + line
item in one call), update, duplicate, activate, and manage budgets, bids, targeting,
and creatives. See [Campaign management](/advertisers/api/campaigns) for the
endpoint reference and examples.

### Reporting

`GET /v1/advertiser/reporting/campaigns` returns aggregated impressions,
clicks, spend, and derived KPIs from daily rollups. Filter by date range,
campaign IDs, and breakdown (`campaign` or `daily`). See
[Advertiser reporting](/advertisers/api/reporting) for parameters, metrics,
and examples.

<Note>
  Creating a campaign requires a `user_id` in the request body. The API key identifies
  your **organization**, not a single user, so you must pass a user who belongs to
  that org. The service rejects a `user_id` outside your org with `403`.
</Note>

## Machine-readable contract

The full OpenAPI 3.1 spec is served by the running API:

```
GET https://api.adgentek.ai/webapi/openapi.yaml
```

Use it for codegen, Postman import, or automated reference generation. Prefer the
spec over hand-maintained endpoint tables when they diverge.

## Health check

No authentication required:

```bash theme={null}
curl https://api.adgentek.ai/webapi/health
```

Returns service status and whether the database connection is up.

## Related documentation

This API is **not** the publisher `/get-ad` endpoint. Publishers integrating ad
delivery should use the
[REST API integration guide](/publishers/integrations/rest-api) instead.

For product context on campaigns and measurement, see
[Campaign setup](/advertisers/campaign-setup) and
[Measurement](/advertisers/measurement).