Publisher Public API migration reference for LLM coding agents

Audience: This file is written to be consumed by an LLM coding agent (Claude Code or similar) tasked with migrating a client's integration from the legacy Unity "Monetize Manage API" (

/monetize/v1/...

) to the new Unity Ads Publisher Public API (

/ads/publisher/public/v1/...

). It is split into self-contained entity blocks. Each block states what changed and exactly what to do. Read the Conceptual model change and Global changes sections first — they apply to every block.

How to use this file (instructions for the agent)

1. Treat the two contracts as the source of truth, not this prose. Legacy =

   ads-selfserve/src/servers/http-internal/openapi/public-v1.yaml

   . New =

   ads-unified-platform/openapi/publisher/platform-public-v1-routes.yaml

   .
2. Migrate one entity block at a time, in the order given (Applications → Placements → org-level lists). Do not start a block until the one it depends on compiles/passes.
3. When a legacy feature is listed under 🚫 No equivalent, do not invent or guess an endpoint. Stop and surface it to the human as an open question. The most important example is eCPM Targets, which do not exist in the new API.
4. After each block, re-map field names per the field tables; never assume a field carried over unchanged unless the table says "unchanged".

Conceptual model change (read this first)

Legacy model (nested, project-centric)

Organization└── Project                       (spans BOTH stores; has coppa + adsProvider)    └── Store (apple | google)    (in the URL path)        └── Ad-Unit               (adFormat, skip/mute/banner settings live here)            └── Placement                └── eCPM Target    (geo-based floor prices)

New model (flat, application-centric)

Organization└── Application                   (ONE platform + ONE store each; has privacy + testMode)    └── Placement                 (adFormat + adFormatConfigurations live here; no targets)Organization└── Test Device                   (NEW, org-scoped)

The four shifts that drive every transformation

apple

google

projectId

projectName

adFormatConfigurations

adFormat

POST

PUT

DELETE

Global changes (apply to all endpoints)

https://services.api.unity.com

https://services.api.unity.com/ads/publisher

https://staging.services.api.unity.com/ads/publisher

/monetize/v1

/public/v1

…/monetize/v1/organizations/{orgId}/projects

…/ads/publisher/public/v1/organizations/{organizationId}/applications

unity

ads

organizationId

organizationId

projectId

applicationId

dryrun

showarchived

isArchived

archive: true/false

DELETE

PATCH …/restore

Rate limits changed (update any client-side backoff assumptions)

GET

POST

PATCH

PUT

DELETE

Master endpoint map

getProjects

GET /monetize/v1/organizations/{orgId}/projects

publicOrganizationApplications

GET /public/v1/organizations/{orgId}/applications

postProjects

POST /monetize/v1/organizations/{orgId}/projects

publicCreateApplication

POST /public/v1/organizations/{orgId}/applications

getProjectDetails

GET /monetize/v1/projects/{projectId}

publicGetApplicationById

GET /public/v1/organizations/{orgId}/applications/{applicationId}

updateProjectDetails

PATCH /monetize/v1/projects/{projectId}

publicUpdateApplication

PATCH /public/v1/organizations/{orgId}/applications/{applicationId}

getAdUnitsByProject

getAdUnitsByProjectStore

createAdUnits

updateAdUnits

getAdUnits

patchAdUnits

…/projects/{projectId}/[stores/{storeName}/]adunits[/{adUnitId}]

createPlacements

POST …/adunits/{adUnitId}/placements

publicCreatePlacement

POST /public/v1/organizations/{orgId}/applications/{applicationId}/placements

GetPlacements

GET …/adunits/{adUnitId}/placements

publicApplicationPlacements

GET …/applications/{applicationId}/placements

getPlacement

GET …/placements/{placementId}

publicGetPlacementDetails

GET …/applications/{applicationId}/placements/{placementId}

updatePlacements

updatePlacement

PATCH …/placements[/{placementId}]

publicUpdatePlacement

PUT …/applications/{applicationId}/placements/{placementId}

archive:true

PATCH …/placements/{placementId}

publicArchivePlacement

DELETE …/applications/{applicationId}/placements/{placementId}

archive:false

PATCH …/placements/{placementId}

publicUnArchivePlacement

PATCH …/applications/{applicationId}/placements/{placementId}/restore

GetPlacements

GET /monetize/v1/organizations/{orgId}/placements

publicOrganizationPlacements

GET /public/v1/organizations/{orgId}/placements

getTargets

createTargets

getTargetDetail

patchTarget

deleteTarget

…/placements/{placementId}/targets[/{targetId}]

publicGetApplicationTestMode

publicUpdateApplicationTestMode

GET

PATCH …/applications/{applicationId}/test-mode

…/organizations/{orgId}/test-devices[/{testDeviceId}]

Block A - Projects → Applications

What changed

• The resource you list/create/read/update is now the Application, not the Project.
• Read/update are now nested under the org (

  /organizations/{orgId}/applications/{applicationId}

  ) and keyed by

  applicationId

  (Unity App id), not the standalone

  /projects/{projectId}

  .
• A legacy project carried both stores; a new application is single-platform. Split accordingly (see transform rules).

• adsProvider

  is gone.

  coppa

  changed from an enum string to a boolean, and moved under a

  privacy

  object alongside the new

  mixedAudience

  boolean.

Endpoint mapping

GET …/organizations/{orgId}/projects

GET …/organizations/{orgId}/applications

POST …/organizations/{orgId}/projects

POST …/organizations/{orgId}/applications

GET …/projects/{projectId}

GET …/organizations/{orgId}/applications/{applicationId}

PATCH …/projects/{projectId}

PATCH …/organizations/{orgId}/applications/{applicationId}

Field mapping — create (

createProject

→

CreateApplicationPublicDto

)

name

name

adsProvider

coppa

"compliant"

"non_compliant"

privacy.coppa

"compliant"

true

"non_compliant"

false

privacy.mixedAudience

privacy

false

stores.apple

stores.google

{storeId, storeUrl}

store

storeId

platform

platform

iOS

Android

iconUrl

projectId

projectName

Field mapping — update (

updateProject

→

UpdateApplicationPublicDto

)

adsProvider

coppa

privacy.coppa

privacy.*

stores

store

storeId

name

kidsSettings

true

Field mapping — response (

project

/

projectDetail

→

ApplicationPublicResponseDto

)

id

id

projectId

id

projectId

name

name

coppa

coppa

mixedAudience

adsProvider

stores

store

storeId

platform

archivedAt

maxCaps

iconUrl

testMode

kidsSettings

Transform rule: one legacy project → N applications

stores.apple

stores.google

POST /applications

platform: iOS

store: AppleAppStore

storeId: <apple.storeId>

platform: Android

store: GooglePlay

storeId: <google.storeId>

projectName: <project.name>

projectId

projectId

Example

POST /monetize/v1/organizations/3573617062594/projects{  "name": "My Game",  "adsProvider": "unity",  "coppa": "non_compliant",  "stores": {    "apple":  { "storeId": "1479198816", "storeUrl": "https://apps.apple.com/..." },    "google": { "storeId": "com.unity.trashdash", "storeUrl": "https://play.google.com/..." }  }}

POST /ads/publisher/public/v1/organizations/3573617062594/applications{  "name": "My Game",  "platform": "iOS",  "store": "AppleAppStore",  "storeId": "1479198816",  "privacy": { "coppa": false, "mixedAudience": false },  "projectName": "My Game"}// → response.projectId = "5a8591dd-..."; reuse it for the second app:POST /ads/publisher/public/v1/organizations/3573617062594/applications{  "name": "My Game",  "platform": "Android",  "store": "GooglePlay",  "storeId": "com.unity.trashdash",  "privacy": { "coppa": false, "mixedAudience": false },  "projectId": "5a8591dd-..."}

Block B — Ad-Units → removed (folded into Application + Placement)

🚫 No equivalent resource

…/projects/{projectId}/[stores/{storeName}/]adunits…

getAdUnitsByProject

getAdUnitsByProjectStore

createAdUnits

updateAdUnits

getAdUnits

patchAdUnits

Where ad-unit data went

adFormat

rewarded

interstitial

banner

adFormat

allowSkipInSeconds

muteVideo

adFormatConfigurations.adminSettings.{allowSkipInSeconds, muteVideo}

bannerRefreshRate

adFormatConfigurations.bannerRefreshRate

adTypes

display

playable

video

placements

adFormat

adFormatConfigurations

Block C — Placements (per-application)

What changed

• Path is now

  …/applications/{applicationId}/placements[/{placementId}]

  — no store/ad-unit segments.
• Individual operations replace batch maps/arrays.

• adFormat

  is required on each placement (was an ad-unit property).
• New

  adFormatConfigurations

  object holds the player/admin settings; shape depends on

  adFormat

  (Rewarded/Interstitial/Banner).
• eCPM

  targets

  are gone from the placement body (see Block E).
• Identifiers: legacy

  placementId

  was a slug (

  ^[\da-zA-Z_-]+$

  ); the new placement

  id

  is a UUID, and the human-readable slug is returned separately as

  key

  (generated from

  name

  ).
• Archive/restore are dedicated operations, not a body flag.
• Per-placement update is

  PUT

  (full replacement), not

  PATCH

  .

Endpoint mapping

POST …/adunits/{adUnitId}/placements

POST …/applications/{applicationId}/placements

GET …/adunits/{adUnitId}/placements

GET …/applications/{applicationId}/placements

isArchived

adFormat[]

GET …/placements/{placementId}

GET …/applications/{applicationId}/placements/{placementId}

PATCH …/placements/{placementId}

PUT …/applications/{applicationId}/placements/{placementId}

PATCH …

{"archive": true}

DELETE …/placements/{placementId}

PATCH …

{"archive": false}

PATCH …/placements/{placementId}/restore

Field mapping — request (

addPlacements[]

/

patchPlacementObject

→

PlacementPublicRequestDto

)

name

name

id

id

key

adFormat

rewarded

interstitial

banner

adFormat

addTargets

targets

placementType

archive

DELETE

restore

adFormatConfigurations

adFormatConfigurations

shape (by

adFormat

)

• rewarded (

  RewardedConfigurations

  ):

  name

  (reward name, required),

  value

  (reward value, required),

  adminSettings

  (

  AdminConfigurations

  ).
• interstitial (

  InterstitialConfigurations

  ):

  adminSettings

  .
• banner (

  BannerConfigurations

  ):

  adminSettings

  ,

  bannerRefreshRate

  (required).

• AdminConfigurations

  :

  allowSkip

  ,

  allowSkipInSeconds

  ,

  videoPlayableSkipInSeconds

  ,

  closeTimerDuration

  ,

  tapsToClose

  ,

  muteVideo

  ,

  disableVideoControlsFade

  ,

  useCloseIconInsteadOfSkipIcon

  .

Field mapping — response (

placement

→

PlacementPublicResponseDto

)

id

key

key

id

name

name

archivedAt

archivedAt

null

placementType

targets

adFormat

status

active

paused

adFormatConfigurations

applicationId

createdAt

updatedAt

⚠️ ID remap is the highest-risk step. Anywhere the client persisted a legacy placement slug as the identifier, it must now store the new UUID

id

for path operations, while the slug survives as

key

. Build and persist a

legacy placement slug → new {id, key}

lookup during migration.

Example

POST /monetize/v1/projects/{projectId}/stores/apple/adunits/{adUnitId}/placements[ { "name": "Rewarded Placement", "id": "rewarded_01",    "addTargets": [ { "value": 18.5, "type": "global" } ] } ]

POST /ads/publisher/public/v1/organizations/{orgId}/applications/{applicationId}/placements{  "name": "Rewarded Placement",  "adFormat": "rewarded",  "adFormatConfigurations": {    "name": "coins",    "value": 100,    "adminSettings": { "allowSkip": true, "allowSkipInSeconds": 5, "muteVideo": false }  }}

Block D — Organization placements list

What changed

targets

adFormat

platform

storeId

id

placementId

Endpoint mapping

GET /monetize/v1/organizations/{orgId}/placements

GET /public/v1/organizations/{orgId}/placements

Field mapping (

placementWithGameId

→

OrganizationPlacementPublicResponseDto

)

id

placementId

Banner_Android

name

name

placementType

placementType

bidding

gameId

gameId

targets

adFormat

rewarded

interstitial

banner

native

platform

ios

android

""

""

storeId

Block E - eCPM Targets Removed

🚫 No equivalent in the new public API

getTargets

createTargets

getTargetDetail

patchTarget

deleteTarget

targets

addTargets

1. Do not map these to any new endpoint. Do not fabricate

   …/targets

   paths.
2. Remove

   targets

   /

   addTargets

   from all placement create/update payloads.
3. If the client's integration manages eCPM floor prices via this API, stop and report this to the human as a blocking gap — eCPM target management is not covered by the new Publisher Public API and must be handled out of band (e.g. via a different Unity surface or product decision). Flag it explicitly; do not silently drop pricing logic without surfacing it.

Block F — Application Test Mode (NEW)

• GET …/applications/{applicationId}/test-mode

  →

  { id, testMode }

• PATCH …/applications/{applicationId}/test-mode

  with

  { "testMode": "forceAll" | "forceOff" }

testMode

Block G — Test Devices (NEW)

• POST …/organizations/{orgId}/test-devices

  —

  CreateTestDevicePublicDto

  { name*, advertisingId*, platform? }

• GET …/organizations/{orgId}/test-devices

  — list (optional

  platform

  filter)

• GET …/organizations/{orgId}/test-devices/{testDeviceId}

  — get one

• PATCH …/organizations/{orgId}/test-devices/{testDeviceId}

  —

  UpdateTestDevicePublicDto

• DELETE …/organizations/{orgId}/test-devices/{testDeviceId}

  — 204

testDeviceId

platform

Android

iOS

OSX

Windows

Linux

WebGL

Windows_Store

PS4

PS5

XboxOne

tvOS

Switch

VisionOS

Suggested migration algorithm (deterministic order for the agent)

1. Config: swap base host to

   …/ads/publisher

   and the path prefix

   /monetize/v1

   →

   /public/v1

   . Keep Basic auth. Remove all

   dryrun

   params.
2. Applications (Block A): for each legacy project, create one application per store; transform

   coppa

   enum→boolean, drop

   adsProvider

   , set

   platform

   /

   store

   /

   storeId

   . Group via

   projectName

   /

   projectId

   . Persist a

   legacy projectId+store → new {applicationId, projectId}

   map.
3. Placements (Block C): for each legacy placement, resolve the owning application from the map, create it individually with

   adFormat

   (from the legacy ad-unit) +

   adFormatConfigurations

   (from ad-unit/admin settings). Drop

   targets

   /

   addTargets

   . Persist

   legacy placement slug → new {id, key}

   .
4. Re-point identifiers: replace stored legacy placement slugs with the new UUID

   id

   for path ops (keep

   key

   for display). Replace stored

   projectId

   -based app refs with

   applicationId

   .
5. Archive semantics: replace

   archive:true/false

   PATCH calls with

   DELETE

   /

   PATCH …/restore

   .
6. List/read shapes: update response parsing per the field tables (esp. org list — Block D).
7. eCPM Targets (Block E): remove target code; report the gap to the human.
8. Optional new features: wire up Test Mode (F) and Test Devices (G) only if requested.
9. Rate limits: cap creates at ≤1/s and ≤60/hour; reads ≤20/s.

Validation checklist (run after migration)

• No request path contains

  /monetize/v1

  ,

  /projects/{

  ,

  /adunits

  ,

  /stores/

  , or

  /targets

  .
• No request body contains

  adsProvider

  ,

  addTargets

  ,

  targets

  , or

  archive

  .

• coppa

  is a boolean everywhere (never

  "compliant"

  /

  "non_compliant"

  ).
• Every placement create/update sends a valid

  adFormat

  and an

  adFormatConfigurations

  matching that format.
• Placement path params use the new UUID

  id

  , not the legacy slug (

  key

  ).
• A legacy project with two stores produced two applications sharing one

  projectId

  .
• eCPM target management was surfaced to the human as an unsupported gap (if the client used it).

Quick reference: 🚫 removed / no-equivalent (do not migrate or fabricate)

• All Ad-Unit endpoints and the ad-unit resource.
• All eCPM Target endpoints and

  targets

  /

  addTargets

  fields.
• Project

  adsProvider

  and

  maxCaps

  .

• dryrun

  and

  showarchived

  query params.
• Client-chosen placement ids (the server assigns the UUID; you keep the slug as

  key

  ).