136 lines
5.1 KiB
Markdown
136 lines
5.1 KiB
Markdown
---
|
|
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
|