---
title: "OMG Platform REST API"
aliases: [omg-api, oliver-omg-api, omg-marketing-ops-api]
tags: [api, oliver, omg, briefs, deliverables, tasks, rest]
sources: [raw/Scalar API Reference.md]
created: 2026-05-08
updated: 2026-05-08
---

# OMG Platform REST API

REST API for the **OMG marketing operations platform** (Oliver internal). Manages briefs, deliverables, projects, tasks, file uploads, and library batch operations.

- **Version:** v2.0.0 (OAS 3.0.3)
- **Base URL:** `https://api.omg.dev.oliver.solutions/{tenantID}/v2`
- **Gateway:** TYK — resolves tenant + user context from the API key before forwarding

## Authentication

Every request requires an `X-Api-Key` header. The TYK gateway uses this key to derive the tenant and user context. No Bearer token or OAuth flow.

```bash
--header 'X-Api-Key: YOUR_SECRET_TOKEN'
```

## Response Format

**Success:**
```json
{ "data": { ... }, "message": "..." }
```
HTTP `200` (read/update/delete) or `201` (created).

**Error — RFC 7807 Problem Details:**
```json
{ "type": "about:blank", "title": "...", "status": 422, "detail": "..." }
```

## HTTP Status Codes

| Code | Meaning |
|------|---------|
| `200` | Read, update, delete succeeded |
| `201` | Resource created |
| `400` | Invalid or missing request parameters |
| `403` | Auth failure — missing or invalid `X-Api-Key` |
| `404` | Resource not found or not in tenant scope |
| `422` | Parameters valid but business logic rejected |
| `500` | Unexpected server error |

## Endpoints

### Briefs `/briefs`

CRUD for marketing briefs.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/briefs` | Create a brief |
| `GET` | `/briefs/{id}` | Get a brief by ID |
| `PATCH` | `/briefs/{id}` | Partial update; include `status: "change_request"` to trigger status transition (all other fields ignored) |
| `DELETE` | `/briefs/{id}` | Delete a brief |

**Create brief fields:** `brief_title`, `slipstream`, `brief_summary`, `brief_deadline` (date), `external_reference`, `business_area`

**PATCH note:** Two modes — status transition (`status` field only) vs field update (any other fields). They are mutually exclusive.

### Tasks `/tasks`

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/tasks` | Create a planning task |

**Fields:** `name`, `start_date` (ISO 8601), `end_date` (ISO 8601), `parent_planning_id`

### Users `/user` and `/users`

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/user?email=&staffid=` | Lookup by email **or** staffid (exactly one required) |
| `GET` | `/user/{id}` | Get user by ID (404 if outside tenant) |
| `PUT` | `/user/{id}` | Update user fields (partial — omitted fields unchanged) |
| `POST` | `/user/{id}/avatar` | Upload JPEG avatar (`multipart/form-data`); returns new avatar URL; thumbnails generated async |
| `GET` | `/users?search=` | List all active users; `search` filters by contains match on name/email/agency/role |

**User fields:** `first_name`, `last_name`, `email_address`, `owning_agency_id`, `owning_agency_name`, `job_role`, `job_role_name`

`owning_agency_id` and `job_role` are validated against FK values on PUT.

### Other Resource Groups (Collapsed in Scalar)

- **Deliverables** — read and update job deliverables
- **Projects** — create and read planning projects and their deliverables
- **Library** — client-specific library batch operations
- **Debug** — development and smoke-test endpoints

## Key Takeaways

- **TYK gateway** handles auth and tenant resolution — pass `X-Api-Key`, nothing else
- **Multi-tenant**: all paths include `{tenantID}` — scoping is automatic from the key + path combo
- **PATCH briefs** has a two-mode design: status transition OR field update, not both
- **`422`** is the business-logic rejection code — distinct from `400` (bad params)
- **User list** returns `user_dom_small` objects (id, names, email, agency, job_role)
- **Avatar upload** is async — thumbnails are generated by background workers after the POST returns
- Deliverables, Projects, Library are read/update only (no full CRUD visible in this snapshot)

## Usage Example

```bash
# Create a brief
curl 'https://api.omg.dev.oliver.solutions/{tenantID}/v2/briefs' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_SECRET_TOKEN' \
  --data '{
    "brief_title": "Q3 Campaign Brief",
    "brief_summary": "Overview of Q3 requirements",
    "brief_deadline": "2026-06-30",
    "business_area": "UK/Marketing/Digital"
  }'

# List users with search
curl 'https://api.omg.dev.oliver.solutions/{tenantID}/v2/users?search=jane' \
  --header 'X-Api-Key: YOUR_SECRET_TOKEN'
```

## Related

- [[wiki/client-knowledge/ferrero|Ferrero]] — uses OMG platform for AC Booking Tool (`CSV/OMG`)
- [[wiki/client-knowledge/3m|3M]] — OMG Portal project (One2Edit + OMG)
- [[wiki/tech-patterns/box-api-integration|Box API Integration]] — often paired with OMG for asset workflows
- [[wiki/tech-patterns/azure-ad-msal-auth|Azure AD MSAL Auth]] — Oliver's standard auth (contrast: OMG uses X-Api-Key via TYK)

## Sources

- `raw/Scalar API Reference.md` — Scalar-rendered OpenAPI spec snapshot, v2.0.0, captured 2026-05-07