obsidian/wiki/tech-patterns/omg-api 2.md

title	aliases	tags	sources	created	updated
OMG Platform REST API	omg-api oliver-omg-api omg-marketing-ops-api	api oliver omg briefs deliverables tasks rest	raw/Scalar API Reference.md	2026-05-08	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.

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

Response Format

Success:

{ "data": { ... }, "message": "..." }

HTTP 200 (read/update/delete) or 201 (created).

Error — RFC 7807 Problem Details:

{ "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

# 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 — uses OMG platform for AC Booking Tool (CSV/OMG)
• wiki/client-knowledge/3m — OMG Portal project (One2Edit + OMG)
• wiki/tech-patterns/box-api-integration — often paired with OMG for asset workflows
• wiki/tech-patterns/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