# MeetROAS Customer API

Read performance and create or edit Apps and Campaigns with the complete Dashboard editor fields through the REST API.

## Quickstart

1. Go to Dashboard `/account/api`'s "API" tab to create a Key
2. The complete Key is shown only once; immediately store it in an environment variable securely (e.g. `read -rs MEETROAS_API_KEY` then `export MEETROAS_API_KEY`, a password manager, or CI secrets)
3. Copy the following command and run it directly; the shell expands the variable automatically

```bash
curl https://open.meetroas.com/v1/me \
  -H "Authorization: Bearer $MEETROAS_API_KEY"
```

## Authentication

Create a Key in Dashboard `/account/api`'s "API" tab. The complete Key is shown only once, format: `mrp_<id>_<secret>`

**Authorization header:**

```
Authorization: Bearer mrp_<id>_<secret>
```

**Scopes:**

- `apps:read` — Read app list
- `campaigns:read` — Read campaigns
- `performance:read` — Read performance data (including placement insights)
- `apps:write` — Create and edit Apps; requires apps:read
- `campaigns:write` — Create and edit Campaigns; requires apps:read and campaigns:read

Existing keys and the default issuance option remain read-only.

## Quota and limits

| Plan | units/minute | units/day (UTC) |
|---|---|---|
| Free | 30 | 1,000 |
| Starter | 60 | 5,000 |
| Pro | 120 | 20,000 |
| Scale | 300 | 100,000 |

**Unit costs:**

- `GET /v1/me`, `GET /v1/apps`, `GET /v1/apps/{appSlug}/campaigns`: 1 unit
- `GET /v1/apps/{appSlug}/campaigns/{campaignId}/placement-insights`: 10 units
- `GET /v1/.../editor`, `GET /v1/media/staging/{receipt}`: 1 unit
- Create/edit App or Campaign, stage media: 5 units
## REST API Reference

**Base URL:** `https://open.meetroas.com/v1`

### GET /v1/me

Required scopes: any valid Key · Quota units: 1

```bash
curl "https://open.meetroas.com/v1/me" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"
```

### GET /v1/apps

Required scopes: apps:read · Quota units: 1

```bash
curl "https://open.meetroas.com/v1/apps" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"
```

### GET /v1/apps/{appSlug}/campaigns

Required scopes: apps:read + campaigns:read · Quota units: 1

```bash
curl "https://open.meetroas.com/v1/apps/my-game/campaigns" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"
```

### GET /v1/apps/{appSlug}/campaigns/{campaignId}/placement-insights

Required scopes: apps:read + campaigns:read + performance:read · Quota units: 10

**Query parameters:**

- `range`: `today` | `7d` | `30d` (default: `7d`)
- `dimension`: `placement` | `subPlacement` | `creative` | `upstreamCampaign` | `country` | `environment` (default: `placement`)

```bash
curl "https://open.meetroas.com/v1/apps/my-game/campaigns/brand:brand_9f2c41ab7d0e4c518a63b2d7e04f19c5/placement-insights?range=7d&dimension=placement" \
  -H "Authorization: Bearer $MEETROAS_API_KEY"
```

### Create and edit App / Campaign

All writes require Idempotency-Key (8–128 characters); PATCH also requires the If-Match ETag from the matching /editor GET. Stale versions return 412.

- `POST /v1/apps`, `PATCH /v1/apps/{appSlug}`: JSON with the Dashboard App editor's content, primary, destination, objective, and media sections.
- `GET /v1/apps/{appSlug}/editor`: Complete editable data and ETag.
- `POST /v1/apps/{appSlug}/campaigns`, `PATCH /v1/apps/{appSlug}/campaigns/{campaignId}`: Multipart with every Dashboard Campaign editor field; JSON {enabled:boolean} changes secondary Campaign status.
- `GET /v1/apps/{appSlug}/campaigns/{campaignId}/editor`: Complete editable data and ETag. Primary Campaign uses App fields and apps:write.
- `POST /v1/media/staging`: Stage icon, screenshots, hero, or video; create targets are new-app:{Idempotency-Key} or new-page:{appId}:{Idempotency-Key}.

## Errors and retries

| HTTP | Meaning | Handling |
|---|---|---|
| 401 `invalid_api_key` | Key invalid, revoked, expired, or account/creator disabled | Do not retry; use a different Key |
| 403 `forbidden_scope` | Insufficient scopes | Do not retry; use a Key with sufficient scopes |
| 404 `not_found` | App slug or campaign id not found | Use /v1/apps, /v1/apps/{slug}/campaigns to get correct id |
| 409 `conflict` / `idempotency_conflict` | Plan limit or creation key reused with different content | The latter includes the createdId |
| 412 `precondition_failed` | Editor snapshot changed | Reload /editor and ETag |
| 422 `unprocessable_entity` | Editor field validation failed | Inspect fieldErrors |
| 428 `precondition_required` | Edit missing If-Match | Fetch the /editor ETag first |
| 429 `rate_limited` / `quota_exceeded` | units or request count exceeded | Wait per Retry-After |
| 503 `service_unavailable` | Dependency temporarily unavailable | Wait per Retry-After |

## Differences from Partner Event API

| Feature | Partner Event API | Customer API |
|---|---|---|
| Audience | Destination platform vendors | MeetROAS customers (traffic buyers) and their developers |
| Host | `api.meetroas.com` | `open.meetroas.com` |
| Authentication | HMAC signature | Bearer token |
| Direction | Receive conversion events (write) | Read account and performance; manage Apps and Campaigns |
## Phase 2 preview

OAuth 2.1 is planned for Phase 3.

---

Full OpenAPI spec: https://open.meetroas.com/openapi.json