iQ Publish API

To learn more about this API and available object fields, see iQ Profiles API and iQ Profiles Objects.

How it works

The iQ Publish API extends the /v3/tiq API surface with three publish capabilities. You can publish an existing saved version to one or more environments, poll the status of a publish request, or combine a profile save and publish into a single PATCH operation.

Authentication

The bearer token is used to authenticate all API calls and not the API key. The API key is only used in the authentication call. In addition to the bearer token, the authentication response includes a region-specific hostname that must be used in subsequent server-side API calls.

To learn about generating a bearer token from the API key, see Authentication.

Publish an existing version

Use this endpoint when a saved profile version already exists and you want to publish it without modifying the profile. You must supply the exact versionId to publish. The API does not implicitly publish the latest version.

POST /v3/tiq/accounts/{ACCOUNT}/profiles/{PROFILE}/publish

Request parameters

Parameter	Type	Required	Description
`versionId`	String	Yes	The version ID of the saved profile to publish. Version IDs use the format `YYYYMMDDhhmm`. For example, `202608131215`.
`operatorId`	String	Yes	The identifier recorded for the publishing operator. This is typically the email address of the Tealium account performing the operation.
`publishTargets`	Array of strings	Yes	One or more target environment names. Default targets are `dev`, `qa`, and `prod`. Custom environments may also be used as targets when configured on the profile. For more information, see Custom publish environments. Target names are normalized to lowercase and must contain only letters, numbers, and dashes.
`title`	String	Yes	The publish title. Titles longer than 128 characters are rejected.
`notes`	String	Yes	Notes recorded with the publish request.

If the request includes multiple targets, all targets must pass the permission check. A request is not partially accepted for only the targets you are authorized to publish to.

Example request

curl --request POST \
  --url "https://platform.tealiumapis.com/v3/tiq/accounts/{ACCOUNT}/profiles/{PROFILE}/publish" \
  --header "Authorization: Bearer {TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "versionId": "202608131215",
    "operatorId": "user@example.com",
    "publishTargets": ["qa"],
    "title": "API publish",
    "notes": "Publishing version 202608131215 to QA"
  }'

Response

A successful response means the publish request was accepted and queued, not that publishing is complete. Use the publishId from the response to poll the status endpoint.

Expand to view example response

Field	Description
`publishId`	UUID for the publish request. Use this value to poll the status endpoint.
`account`	The Tealium account name.
`profile`	The Tealium profile name.
`versionId`	The profile version submitted for publish.
`operatorId`	The operator identifier supplied in the request.
`createdDate`	The publish request creation time in UTC.
`publishTargets`	Target records created for the publish request. Each entry contains `target`, `publishTargetId`, and `distroDate`.
`title`	The publish title supplied in the request.
`notes`	The publish notes supplied in the request.
`revisionId`	The revision identifier associated with the published profile data.

Error codes

Error code	Description
400	Missing required field, malformed target name, or title longer than 128 characters.
401	Missing or malformed bearer token.
403	Insufficient publish permission for the account, profile, or one or more requested targets.
404	Account, profile, or version identifier not found.
409	Concurrent user or publish conflict.
422	Publish target validation failed or profile referential integrity error.

Check publish status

Use this endpoint to poll the status of a publish request after a POST publish or PATCH save-and-publish call.

GET /v3/tiq/accounts/{ACCOUNT}/profiles/{PROFILE}/publish/{PUBLISH_ID}/status

Path parameters

Parameter	Description
`ACCOUNT`	The Tealium account name.
`PROFILE`	The Tealium profile name.
`PUBLISH_ID`	The `publishId` returned by the POST publish endpoint, or the `publish.data.publishId` value in a PATCH save-and-publish response.

Example request

curl --request GET \
  --url "https://platform.tealiumapis.com/v3/tiq/accounts/{ACCOUNT}/profiles/{PROFILE}/publish/{PUBLISH_ID}/status" \
  --header "Authorization: Bearer {TOKEN}" \
  --header "Accept: application/json"

Response

Expand to view example response

Field	Description
`publishId`	UUID identifying the overall publish request.
`publishTargetEventResponses`	One status entry for each target event record. Check the latest state for each target.
`publishTargetEventId`	UUID identifying the status event record. This value changes as the target progresses.
`publishTargetId`	UUID identifying the target submission within the publish request.
`publishTargetEventType`	The lifecycle event type emitted by the publish service.
`publishTargetState`	The coarse state derived from the event type.
`detail`	Optional diagnostic detail. This value may be `null`.
`createdDate`	UTC timestamp for the event.

Publish states

Event type	State	Meaning
`initialising_publish`	`queued`	The request is being initialized.
`tag_generation_queued`	`queued`	The target is waiting for tag generation.
`tag_generation_started`	`processing`	Tag generation has started.
`publish_distro_queued`	`processing`	Distribution is queued.
`publish_distro_starting`	`processing`	Distribution is starting.
`publish_success`	`published`	The target completed successfully.
`publish_fail`	`stopped`	The target failed or was stopped.

For requests with multiple targets, check the state of every target. A publish is complete only when all targets reach published. A publish has failed when any target reaches stopped.

Error codes

Error code	Description
401	Missing or malformed bearer token.
403	Insufficient publish permission for the account or profile.
404	Account, profile, or publish identifier not found.
429	Request rate exceeded. Reduce the polling frequency and retry.

Save and publish

Use this endpoint when you want to save a profile change and publish the resulting version in one operation. The service uses the version created by the save — do not supply a versionId for the publish portion.

PATCH /v3/tiq/accounts/{ACCOUNT}/profiles/{PROFILE}

Use the same operationList body as the existing PATCH operations for tags, variables, load rules, events, and extensions. Add the following fields to enable save-and-publish.

Publish fields

All fields in the following table are required when publish is true.

Field	Type	Description
`publish`	Boolean	Set to `true` to enable save-and-publish. When absent or `false`, the existing PATCH save behavior is used.
`publishTargets`	Array of strings	Target environment names to publish to after the save. Default targets are `dev`, `qa`, and `prod`. Custom environments may also be used when configured on the profile. For more information, see Custom publish environments.
`publishTitle`	String	The publish title.
`publishNote`	String	Notes recorded with the publish request.
`operatorId`	String	The identifier recorded for the publishing operator.

The notes field is the version save note. The publishNote field is the publish note. Provide both fields when performing a save-and-publish operation.

Example request

curl --request PATCH \
  --url "https://platform.tealiumapis.com/v3/tiq/accounts/{ACCOUNT}/profiles/{PROFILE}" \
  --header "Authorization: Bearer {TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "versionTitle": "API patch publish",
    "saveType": "saveAs",
    "parentVersion": "202608131150",
    "notes": "Added page_type variable",
    "operationList": [
      {
        "op": "add",
        "path": "/variables",
        "value": {
          "object": "variable",
          "name": "page_type",
          "alias": "Page Type",
          "type": "udo",
          "notes": "UDO variable"
        }
      }
    ],
    "publish": true,
    "publishTargets": ["qa"],
    "publishTitle": "API patch publish",
    "publishNote": "Publishing via save-and-publish",
    "operatorId": "user@example.com"
  }'

Response

When publish is true, the response contains two top-level sections: profile and publish.

Expand to view example response

Field	Description
`profile`	The saved profile response. The `version` field contains the version ID used for the publish.
`publish.status`	`success` when the publish was submitted successfully. `failed` when a permission, validation, or publish-stage error occurred.
`publish.data`	The publish response data. On success, this contains `publishId` and target records. On failure, this contains error details.

An HTTP 200 response does not confirm that publishing succeeded. When publish.status is failed, the profile save completed but the publish did not. Always check publish.status, and use publish.data.publishId to poll the status endpoint only when publish.status is success.

The save and publish steps are not atomic. If the save completes and the publish fails, the profile save is not reversed. Verify the profile state with a GET request before retrying.

Error codes

Error code	Description
400	Missing required field, malformed target name, invalid PATCH body, or title longer than 128 characters.
401	Missing or malformed bearer token.
403	Insufficient publish permission for the account, profile, or one or more requested targets.
404	Account, profile, or version identifier not found.
409	Concurrent user or publish conflict.
422	Publish target validation failed or profile referential integrity error.
429	Request rate exceeded.