> 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/api-reference/readme/management-api.md). # Management and delivery API reference Integrate with the Podigee Ad Server management, hosting exchange, public delivery, and analytics interfaces with safe authentication, versioning, retries, and pagination. The **Podigee Audio Video Ad Server** APIs connect a hosting platform, an ad operations system, an owned player, or a reporting service to Podigee. The web application and the APIs use the same versioned domain state. An API client must use the declared command and evidence boundaries. It must not write product tables directly. The machine-readable contracts are the authority for field names, schemas, response codes, and examples. This page explains which API to use and how to operate it safely. ## API surfaces | API | Base URL | Who uses it | Authentication | | ------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------- | | Management API v1.0.0 | `https://api.podigee.com/{management-api-base-path}` | Campaign, Creative, Inventory, policy, report, and evidence integrations | OAuth 2.0 authorization code | | Hosting Exchange API v1.0.0 | `https://api.podigee.com/{hosting-exchange-base-path}` | Podigee hosting and distribution systems that exchange content and serving authority | OAuth 2.0 client credentials | | Public Delivery API v1.3.1 | `https://media.podigee.com/{public-delivery-base-path}` | RSS clients, HLS players, Apple playback, owned players, and tracking clients | Signed token in the URL or event request | | Audience Analytics Sink API v1 | Contract-specific | An approved analytics write plane | Bearer token | | Internal Serving API | Private service network | Podigee request-time serving services only | Mutual TLS | The internal serving API is not a customer integration surface. Do not expose it to a public client. ## Management API resources The Management API uses workspace-scoped resources and typed commands. | Operation | Endpoint | Purpose | | --------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | List resources | `GET /workspaces/{workspace_id}/resources/{resource_type}` | List one declared resource type. | | Read a resource | `GET /workspaces/{workspace_id}/resources/{resource_type}/{resource_id}` | Read the current immutable revision and lifecycle state. | | Read versions | `GET /workspaces/{workspace_id}/resources/{resource_type}/{resource_id}/versions` | Read immutable history. | | Execute a command | `POST /workspaces/{workspace_id}/commands/{command_type}` | Request one declared state change. | | Read an operation | `GET /workspaces/{workspace_id}/operations/{operation_id}` | Poll durable asynchronous work. | | Read a receipt | `GET /workspaces/{workspace_id}/receipts/{receipt_id}` | Read the command or authority receipt. | | Read a decision trace | `GET /workspaces/{workspace_id}/decisions/{decision_id}/trace` | Read an authorized redacted replay trace. | | Provision a workspace | `POST /workspace-provisioning` | Create the first workspace boundary through the restricted authority flow. | Resource reads are safe and repeatable. Consequential changes use a command type from the current command catalog. A generic resource update is not a supported write operation. ## Authentication and scopes Use OAuth 2.0 authorization code flow for a user or service integration that acts within a workspace. Request only the scopes that the integration needs. | Scope | Allows | | ---------------------- | ----------------------------------------------------------------- | | Management read scope | Read authorized workspace state, versions, reports, and receipts. | | Management write scope | Execute authorized management commands. | | Diagnostics scope | Read purpose-bound diagnostic and decision traces. | | Bootstrap scope | Use the restricted first-workspace provisioning operation. | Hosting Exchange uses client credentials with its configured machine scope. It is a machine-to-machine boundary for signed content authority, surface capability, delivery alias, platform evidence, and serving-intent exchange. Public delivery endpoints do not accept a management OAuth token. They use an opaque, signed, purpose-bound token. Treat a delivery token as a secret and do not log it. ## Execute a command safely A command request contains the command type, the exact subject and version, the proposed changes, and the reason or operation context required by the command catalog. ```http POST /{management-api-base-path}/workspaces/ws_demo/commands/publish_campaign HTTP/1.1 Host: api.podigee.com Authorization: Bearer Idempotency-Key: campaign-publish-ws_demo-campaign-7-v3 If-Match: "campaign-v3" Content-Type: application/json ``` ```json { "subject": { "type": "campaign", "id": "campaign_demo", "version": 3 }, "changes": { "publication": "requested" }, "reason": "Approved campaign is ready for the selected delivery surfaces" } ``` The server validates permission, workspace scope, current version, policy, review mode, and idempotency before it accepts the command. A successful acceptance returns an operation reference. It does not mean that media delivery is complete. ## Poll asynchronous work Media preparation, forecast calculation, external platform submission, report generation, and reconciliation can be asynchronous. Poll the operation endpoint instead of repeating the command. ```http GET /{management-api-base-path}/workspaces/ws_demo/operations/op_7f3a HTTP/1.1 Host: api.podigee.com Authorization: Bearer ``` The operation reports a stable state such as `accepted`, `running`, `waiting_review`, `succeeded`, `failed`, or `cancelled`. It includes the current subject version, result or problem reference, receipt reference when available, and the next safe action. Retry a read when the network fails. Retry a command only with the same idempotency key and the same canonical payload. Never create a new key after an ambiguous command response until you have read the original operation or receipt. ## Idempotency and concurrency All consequential POST commands require an idempotency key. The key is scoped to the authenticated client, workspace, command type, and canonical payload. * The same key and same payload return the original operation or receipt. * The same key and a different payload return an idempotency conflict. * A new subject version requires a new key. * `If-Match` protects a command from changing a stale version. * A rejected command does not create a paid delivery or finance result. * A provider or platform operation keeps its external receipt and ambiguity state. Use a stable business operation identity. Do not use a random key for every network retry. ## Pagination and filtering List endpoints use cursor pagination. The response provides an opaque `next_cursor` when more rows are available. ```http GET /{management-api-base-path}/workspaces/ws_demo/resources/campaigns?limit=50 HTTP/1.1 Host: api.podigee.com Authorization: Bearer ``` Use the returned cursor without decoding or modifying it. Keep the workspace, resource type, filter, and sort context unchanged while you page. A new filter or sort starts a new list request. The server applies the declared maximum limit. It does not promise stable order after a new version is published unless the contract declares the sort key. ## Hosting Exchange API Hosting Exchange connects the content and distribution system with the monetization authority. It uses signed source events and durable operations. | Resource | Use | | ------------------- | ----------------------------------------------------------------------------- | | Content snapshot | Submit original signed source events and inspect the accepted mapping. | | Content revocation | Stop new serving for one source version without deleting history. | | Surface capability | Publish exact delivery, measurement, client, and platform capabilities. | | Delivery alias | Register or version a stable public URL and its source authority. | | Delivery resolution | Resolve a source, ad-free, platform-controlled, or clean route. | | Platform evidence | Import source-labeled delivery, revenue, or engagement evidence. | | Serving intent | Read or acknowledge the exact version applied by the hosting execution plane. | | Operation | Read the durable state of a hosting exchange operation. | Every write uses the configured Hosting Exchange scope and an idempotency key. Content authority messages are individually signed and version chained. The API rejects unknown keys, invalid signatures, changed duplicates, gaps, forks, and cross-workspace identities. ## Public delivery API The Public Delivery API is for clients that need media or events. It provides: * stable enclosure resolution and progressive audio with `GET`, `HEAD`, and byte ranges; * immutable audio chapters; * immutable and personalized HLS playlists; * HLS timelines, chapters, media, captions, and I-frame resources; * Apple dynamic asset lists and presentation bindings; * bounded VAST responses for signed opportunities; * signed idempotent delivery events through `GET` or `POST` when the surface requires it. The public client receives only the token and representation needed for the request. It does not receive Campaign targeting, rates, budgets, internal reasons, or listener identity. ## Versioning and deprecation The API version is part of the base URL and the contract metadata. A new version is required for a breaking change. Additive fields are ignored only when the contract says they are optional and unknown-field behavior is defined. When a resource, field, command, or endpoint is deprecated, the API documentation shows: 1. The deprecation date. 2. The last supported version. 3. The replacement operation. 4. The migration behavior. 5. The removal or sunset date. Do not infer support from an endpoint that answers today. Check the current contract and capability state before activation. ## Errors and receipts Errors use a stable problem type, a short code, a safe message, and a trace or operation reference. The response can include the exact subject version, field path, retry class, and recovery link. | Error class | Retry rule | | ----------------------------- | ------------------------------------------------------------------------------------------ | | Authentication or scope | Do not retry until the token or grant is repaired. | | Permission or workspace scope | Do not retry with a broader token. Request the correct grant. | | Version conflict | Read the current version and create a new approved command. | | Idempotency conflict | Reuse the original key only after the payload is corrected or the operation is reconciled. | | Validation or policy | Repair the exact field or policy input. | | Rate limit or timeout | Follow `Retry-After` or the contract retry boundary. | | Provider or platform result | Read the operation and provider receipt before retrying. | | Internal failure | Use the operation reference and support workflow. Do not repeat blindly. | Receipts prove the accepted operation, not necessarily the final listener or viewer result. Use the delivery evidence and report APIs to confirm qualified delivery and money state. ## Integration checklist Before an integration goes live: 1. Register the client and request the least-privilege scopes. 2. Store tokens and signing keys outside application logs and source control. 3. Read the current OpenAPI contract and command catalog. 4. Implement cursor pagination and opaque ID handling. 5. Send an idempotency key for every write. 6. Use `If-Match` for a versioned change. 7. Poll operations and store receipts. 8. Handle stable errors and retry only the declared classes. 9. Reconcile ambiguous provider or platform operations. 10. Verify one representative delivery and its analytics and money evidence. ## Expected result An integration can read workspace state, request an authorized change, survive network retries, follow asynchronous work, and prove the resulting operation. It uses the correct authority for management, hosting exchange, public delivery, and analytics without bypassing versioning, idempotency, privacy, or evidence rules. --- # 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/api-reference/readme/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.