> For the complete documentation index, see [llms.txt](https://docs.podigee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podigee.com/documentation/grow-and-monetize/monetization/use-the-management-api.md). # Use the management API Use the versioned management API to read Monetization state and run authorized commands safely. Podigee Audio Video Ad Server provides a versioned management application programming interface (API) for approved automation and system integrations. After the first mention, this article uses Podigee Ad Server for the product name. The API reads the same workspace, Campaign, Creative, delivery, report, integration, and evidence state that you see in the One Podigee application. The API is a control-plane interface. It does not replace request-time media delivery or the analytics pipeline. ## Before you start * You have an approved API client and a permitted service principal. * You know the workspace ID and the resource or command that you need. * You have the minimum OAuth scope for the operation. * You have a safe place to store the access token. * You understand which commands can change delivery, money, access, or integration state. Do not put an access token in source code, a browser URL, a report, or a support message. Use a secret manager and rotate credentials through your organization's access process. ## Connect to the API Use the current management API base URL shown in the API Reference. Use OAuth 2.0 authorization code flow. Request only the scopes that the integration needs: * the read scope reads authorized workspace state; * the write scope runs authorized commands; * the diagnostics scope reads purpose-bound decision diagnostics; and * the bootstrap scope is restricted to the initial verified workspace bootstrap flow. The API checks the token, workspace scope, resource permission, and command authority separately. An access token does not grant access to every resource in the workspace. ## Read resources Use the resource endpoints to read current state and immutable history. ``` GET /workspaces/{workspace_id}/resources/{resource_type} GET /workspaces/{workspace_id}/resources/{resource_type}/{resource_id} GET /workspaces/{workspace_id}/resources/{resource_type}/{resource_id}/versions ``` Examples of resource types include Campaigns, line items, Creatives, breaks, Inventory packages, forecast snapshots, reports, integrations, operations, receipts, and audit events. Use the resource inventory in the API Reference as the source of truth for the current list. For a list request: 1. Set the workspace ID and resource type. 2. Set `limit` between 1 and 200 when the default page size is not suitable. 3. Store the returned cursor. 4. Use the cursor to request the next page. 5. Apply the supported `filter` value only when the resource contract defines it. Do not use a page number as a cursor. A cursor represents the API's current page position. For a single resource, read the current revision and lifecycle state. Use the versions endpoint when you need the immutable history. Keep the version ID, revision, and digest with any later command. ![The current One Podigee report form opens from a Campaign with Campaign delivery selected and the Campaign scope already set.](https://2032417310-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbqUKO6lljHGzkEAzliPI%2Fuploads%2Fgit-blob-a5f134f5e9c76966a2d3bbe1d02863ba0b9b3b3a%2Fdoc-monetization-072-create-scoped-report.png?alt=media) *The API and the application use the same report scope and versioned meaning.* ## Run a command Writes use the command endpoint: ``` POST /workspaces/{workspace_id}/commands/{command_type} ``` The command type is declared in the command catalog. The request envelope contains the actor, workspace scope, expected versions, command payload, and correlation data. 1. Read the current resource and version first. 2. Build the exact command payload required by the command contract. 3. Set an `Idempotency-Key` that is unique for the intended operation and at least 16 characters. 4. Include the expected version for every mutable subject required by the command. 5. Send the command with the approved write scope. 6. Store the response receipt or durable operation ID. 7. Read the final result before starting a dependent command. The API can return: * **200:** the command completed and returned a receipt; * **202:** the command was accepted as a durable operation and must be polled; or * a typed `application/problem+json` error. Do not retry a write with a new idempotency key when the response is uncertain. Reuse the same key and the same request body. The API returns the original result when it already accepted the command. The same key with a changed body is a conflict. ## Follow a durable operation When a command returns 202, read its operation state: ``` GET /workspaces/{workspace_id}/operations/{operation_id} ``` Poll at a reasonable interval. Stop when the operation reaches its terminal state. Keep the operation ID, final state, result references, and failure reason in your integration log. An asynchronous operation can be accepted before its external destination test, media preparation, or report run finishes. A 202 response is not proof of activation or delivery. ## Read receipts Use the receipt endpoint after a command or authority change: ``` GET /workspaces/{workspace_id}/receipts/{receipt_id} ``` The receipt identifies the command, actor, exact versions, result, event, and any durable operation reference that the API can expose. Use it as the machine-readable confirmation of a completed change. ![The current One Podigee Orbit activity record shows the completed partner-operations action with short, copyable references and a completed status.](https://2032417310-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbqUKO6lljHGzkEAzliPI%2Fuploads%2Fgit-blob-19dc99bc7fff181e4ea057a652391b8f4bfd75f5%2Fdoc-monetization-075-notification-receipt.png?alt=media) *Keep the receipt with the exact version that the command changed.* ## Read a decision diagnostic Decision traces contain sensitive operational information. Request the purpose-bound diagnostic operation first, then read the authorized trace: ``` GET /workspaces/{workspace_id}/decisions/{decision_id}/trace ``` The request needs the approved diagnostics scope and the exact completed trace operation ID. It also needs a diagnostic purpose. The trace is redacted and read-only. It does not grant permission to change a Campaign, Flight, policy, or provider. ## Handle common errors * **401 Unauthorized:** refresh the OAuth token or correct the authorization flow. * **403 Forbidden:** request the missing scope, permission, or workspace authority. Do not broaden the token without a business reason. * **404 Not found:** confirm the workspace, resource type, and public ID. * **409 Version conflict:** read the current version, compare the user's intended change, and submit a new command with the current expected version. * **422 Typed problem:** correct the command payload or required evidence. Preserve the problem details in the integration log. * **429 Rate limit:** respect the retry guidance and reduce request volume. * **5xx or network failure:** reuse the same idempotency key for a write after checking whether the operation or receipt already exists. Do not treat a network timeout as proof that no command ran. Read the operation or receipt first. ## Safe automation rules * Use reads to discover current versions before writes. * Keep one idempotency key for one intended write. * Do not mutate an immutable version in place. * Wait for a terminal operation before starting a dependent command. * Store receipts and short, copyable public references, not raw secrets. * Use the application for review, approvals, and visual inspection when a command has a high business or delivery effect. * Keep API errors and recovery evidence visible to the operator. ## Expected result The integration can read authorized state, run version-aware commands, follow asynchronous work, and retain durable receipts. Repeated requests do not create duplicate state or external effects. The API and the One Podigee application remain two interfaces to the same governed Monetization state. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.podigee.com/documentation/grow-and-monetize/monetization/use-the-management-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.