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	An email address recorded in the publish history for audit purposes. This field is not derived from the bearer token automatically.
`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 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. The API rejects the entire request if you lack permission for any requested target.

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.

{
  "publishId": "212ab1da-7503-4691-bf87-f892b450ed5a",
  "account": "my_account",
  "profile": "main",
  "versionId": "202608131215",
  "operatorId": "user@example.com",
  "createdDate": "2026-08-13T20:16:01 UTC",
  "publishTargets": [
    {
      "target": "qa",
      "publishTargetId": "83ff6319-de94-4ac0-b05a-7f19bfb8e34f",
      "distroDate": null
    }
  ],
  "title": "API publish",
  "revisionId": "202608131215",
  "notes": "Publishing version 202608131215 to QA"
}

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 email address supplied in the request and recorded in the publish history for audit purposes.
`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

{
  "publishId": "212ab1da-7503-4691-bf87-f892b450ed5a",
  "publishTargetEventResponses": [
    {
      "publishTargetEventId": "02b71e23-8927-4156-9df0-1f9a87125a44",
      "publishTargetId": "83ff6319-de94-4ac0-b05a-7f19bfb8e34f",
      "publishTargetEventType": "tag_generation_queued",
      "publishTargetState": "queued",
      "detail": null,
      "createdDate": "2026-08-13T20:16:01 UTC"
    }
  ]
}

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.

The status endpoint is rate-limited to one request per second per publish ID. Publish status does not change rapidly, so polling more frequently is unnecessary and returns a 429 error.

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. Poll no more than once per second.

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. Set this to the same value as `title`. Titles longer than 128 characters are rejected.
`publishNote`	String	Notes recorded with the publish request. Set this to the same value as `notes`.
`operatorId`	String	An email address recorded in the publish history for audit purposes. This field is not derived from the bearer token automatically.

The notes and versionTitle fields are the save note and version title recorded when the profile is saved. The publishNote and publishTitle fields are recorded separately when the publish operation runs. Provide all four 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": "Added page_type variable",
    "operatorId": "user@example.com"
  }'

Response

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

Success response

{
  "profile": {
    "account": "my_account",
    "profile": "main",
    "version": "202608131215",
    "minorVersion": "202608131215"
  },
  "publish": {
    "status": "success",
    "data": {
      "publishId": "212ab1da-7503-4691-bf87-f892b450ed5a",
      "account": "my_account",
      "profile": "main",
      "versionId": "202608131215",
      "operatorId": "user@example.com",
      "createdDate": "2026-08-13T20:16:01 UTC",
      "publishTargets": [
        {
          "target": "qa",
          "publishTargetId": "83ff6319-de94-4ac0-b05a-7f19bfb8e34f",
          "distroDate": null
        }
      ],
      "title": "API patch publish",
      "revisionId": "202608131215",
      "notes": "Added page_type variable"
    }
  }
}

Failure response (save succeeded, publish failed)

{
  "profile": {
    "account": "my_account",
    "profile": "main",
    "version": "202608131215",
    "minorVersion": "202608131215"
  },
  "publish": {
    "status": "failed",
    "data": {
      "message": "Publish permission denied for target: prod",
      "account": "my_account",
      "profile": "main",
      "versionId": "202608131215"
    }
  }
}

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.

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

Error codes

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

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.