---
title: iQ Publish API
description: Use the iQ Publish API to publish a saved profile version, check publish status, or save and publish in one operation.
url: https://docs-preview.tealium.com/api/v3/iq-profiles/iq-publish-api/
---
To learn more about this API and available object fields, see [iQ Profiles API](https://docs-preview.tealium.com/iq-profiles-v3-api/) and [iQ Profiles Objects](https://docs-preview.tealium.com/iq-profiles-api-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


<blockquote>
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.
</blockquote>


To learn about generating a bearer token from the API key, see [Authentication](https://docs-preview.tealium.com/api/v3/getting-started/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.

```bash
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](https://docs-preview.tealium.com/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

```bash
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](#check-publish-status).



```json
{
  "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 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.

```bash
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

```bash
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



```json
{
  "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`.

### 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.

```bash
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](https://docs-preview.tealium.com/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. |


<blockquote>
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.
</blockquote>


### Example request

```bash
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`.



```json
{
  "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": "Publishing via save-and-publish"
    }
  }
}
```



| 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. |


<blockquote>
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`.
</blockquote>



<blockquote>
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.
</blockquote>


### 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. |