---
source_url: https://www.pubnub.com/docs/sdks/rest-api/set-channel-metadata
title: Set channel metadata
---

# Set channel metadata

> For AI agents: documentation index at https://www.pubnub.com/llms-full.txt

Sets metadata for the specified channel. Returns the channel object, optionally including custom properties.

**Note:**

* You can change all of the channel's metadata except its identifier.
* Invalid property names are silently ignored and will not cause a request to fail.
* If you set the `custom` property, you must completely replace it since partial updates are not supported.
* The custom object can only contain scalar values.

| Path Parameters |
| --- |
| `sub_key`string—**REQUIRED**Your app's subscribe key from Admin Portal. |
| `channel`string—**REQUIRED**The channel ID to perform the operation on. Must not be empty and can contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero. |

| Query Parameters |
| --- |
| `include`string[]Possible values: [custom, type, status]List of additional/complex metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata. |
| `auth`stringString which is either the auth key (Access Manager legacy) or a valid token (Access Manager) used to authorize the operation if access control is enabled. Authorization token with permissions to perform the request. |
| `signature`stringSignature used to verify that the request was signed with the secret key associated with the subscribe key.If Access Manager is enabled, either a valid authorization token or a signature are required. Check Access Manager documentation for details on how to compute the signature. |
| `timestamp`integerUnix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 seconds offset from NTP. Required if signature parameter is supplied. |

| Header Parameters |
| --- |
| `If-Match`stringAn optional HTTP header that prevents concurrent modifications of the same Channel object by allowing clients to (optionally) request that their updates only be performed if the object hasn't been modified since it was read.You can add If-Match in the Set channel metadata requests and set it to the value of the eTag field from a previous Get channel metadata response body.Imagine the use case where you want to modify an existing Channel object only if it hasn't been modified since the last time you read it.This is how the flow would look like:The client reads the details of a Channel object from App Context API through the Get channel metadata request that returns a response body containing the eTag value representing the object's current state, like 8f6da76a321017a34e0a72ed674393ee., The client sends the eTag value of 8f6da76a321017a34e0a72ed674393ee in the If-Match HTTP header in a subsequent Set channel metadata request, like -H 'If-Match: 8f6da76a321017a34e0a72ed674393ee'., Since that eTag value in the If-Match HTTP header matches the Channel object's current eTag value, the Set channel metadata request will succeed. If the request is sent with an old eTag value that doesn't match the Channel object's current eTag value, the request will fail with a 412 (Precondition failed) error.Note The If-Match precondition checking for concurrent modifications is currently not supported for the membership/members' metadata APIs. These APIs also return an eTag field in the response body, but that field is not yet checked in the request header. |

| Request Body—**REQUIRED**JSON object with channel metadata to set. |
| --- |
| `name`stringPossible values: 1 ≤ lengthThe channel name to perform the operation on. Max. 2,048 characters. Must not be empty or consist only of whitespace characters. |
| `description`stringDescription of the channel. Max. 2,048 characters. |
| `type`stringChannel type. Max. 50 characters. |
| `status`stringChannel status. Max. 50 characters. |
| `custom`objectJSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. |

| Responses |
| --- |
| `200`Successfully set the channel metadata.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.data objectObject with channel metadata used in responses.id string — OPTIONALPossible values: 1 ≤ length ≤ 92The channel ID to perform the operation on. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.updated date-timeDate and time the object was last updated.eTag stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs.name string — OPTIONALPossible values: 1 ≤ lengthThe channel name to perform the operation on. Max. 2,048 characters. Must not be empty or consist only of whitespace characters.description string — OPTIONALDescription of the channel. Max. 2,048 characters.type string — OPTIONALChannel type. Max. 50 characters.status string — OPTIONALChannel status. Max. 50 characters.custom object — OPTIONALJSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `data`objectObject with channel metadata used in responses.id string — OPTIONALPossible values: 1 ≤ length ≤ 92The channel ID to perform the operation on. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.updated date-timeDate and time the object was last updated.eTag stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs.name string — OPTIONALPossible values: 1 ≤ lengthThe channel name to perform the operation on. Max. 2,048 characters. Must not be empty or consist only of whitespace characters.description string — OPTIONALDescription of the channel. Max. 2,048 characters.type string — OPTIONALChannel type. Max. 50 characters.status string — OPTIONALChannel status. Max. 50 characters.custom object — OPTIONALJSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. | `id`string—**OPTIONAL**Possible values: 1 ≤ length ≤ 92The channel ID to perform the operation on. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero. | `updated`date-timeDate and time the object was last updated. | `eTag`stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs. | `name`string—**OPTIONAL**Possible values: 1 ≤ lengthThe channel name to perform the operation on. Max. 2,048 characters. Must not be empty or consist only of whitespace characters. | `description`string—**OPTIONAL**Description of the channel. Max. 2,048 characters. | `type`string—**OPTIONAL**Channel type. Max. 50 characters. | `status`string—**OPTIONAL**Channel status. Max. 50 characters. | `custom`object—**OPTIONAL**JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `data`objectObject with channel metadata used in responses.id string — OPTIONALPossible values: 1 ≤ length ≤ 92The channel ID to perform the operation on. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.updated date-timeDate and time the object was last updated.eTag stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs.name string — OPTIONALPossible values: 1 ≤ lengthThe channel name to perform the operation on. Max. 2,048 characters. Must not be empty or consist only of whitespace characters.description string — OPTIONALDescription of the channel. Max. 2,048 characters.type string — OPTIONALChannel type. Max. 50 characters.status string — OPTIONALChannel status. Max. 50 characters.custom object — OPTIONALJSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. | `id`string—**OPTIONAL**Possible values: 1 ≤ length ≤ 92The channel ID to perform the operation on. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero. | `updated`date-timeDate and time the object was last updated. | `eTag`stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs. | `name`string—**OPTIONAL**Possible values: 1 ≤ lengthThe channel name to perform the operation on. Max. 2,048 characters. Must not be empty or consist only of whitespace characters. | `description`string—**OPTIONAL**Description of the channel. Max. 2,048 characters. | `type`string—**OPTIONAL**Channel type. Max. 50 characters. | `status`string—**OPTIONAL**Channel status. Max. 50 characters. | `custom`object—**OPTIONAL**JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. |
| `id`string—**OPTIONAL**Possible values: 1 ≤ length ≤ 92The channel ID to perform the operation on. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero. |
| `updated`date-timeDate and time the object was last updated. |
| `eTag`stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs. |
| `name`string—**OPTIONAL**Possible values: 1 ≤ lengthThe channel name to perform the operation on. Max. 2,048 characters. Must not be empty or consist only of whitespace characters. |
| `description`string—**OPTIONAL**Description of the channel. Max. 2,048 characters. |
| `type`string—**OPTIONAL**Channel type. Max. 50 characters. |
| `status`string—**OPTIONAL**Channel status. Max. 50 characters. |
| `custom`object—**OPTIONAL**JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. |
| `400`The request body contains invalid data.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `403`Disabled - The subscribe key doesn't have App Context API enabled.Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `412`Conditional operation cannot be performed because the target resource has changed since the last retrieval.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `415`The format of the request body you supplied isn't supported. The request body must be in JSON format.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `429`Request rate limit exceeded.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `500`An internal server error occurred.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `503`Request processing exceeded the maximum allowed time.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |

If-Match
Type:
string
An optional
[HTTP header](https://www.pubnub.com/docs/sdks/rest-api/introduction.md#common-request-headers)
that prevents concurrent modifications of the same Channel object by allowing clients to (optionally) request that their updates only be performed if the object hasn't been modified since it was read.

You can add
If-Match
in the
Set channel metadata
requests and set it to the value of the
[`eTag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)
field from a previous
[**Get channel metadata**](https://www.pubnub.com/docs/sdks/rest-api/get-channel-metadata.md)
response body.

Imagine the use case where you want to modify an existing Channel object only if it hasn't been modified since the last time you read it.

This is how the flow would look like:

1. The client reads the details of a Channel object from App Context API through the
[**Get channel metadata**](https://www.pubnub.com/docs/sdks/rest-api/get-channel-metadata.md)
request that returns a response body containing the
eTag
value representing the object's current state, like
8f6da76a321017a34e0a72ed674393ee
.

1. The client sends the
eTag
value of
8f6da76a321017a34e0a72ed674393ee
in the
If-Match
HTTP header in a subsequent
Set channel metadata
request, like
-H 'If-Match: 8f6da76a321017a34e0a72ed674393ee'
.

1. Since that eTag value in the
If-Match
HTTP header matches the Channel object's current
eTag
value, the
Set channel metadata
request will succeed.

If the request is sent with an old
eTag
value that doesn't match the Channel object's current
eTag
value, the request will fail with a
412
(Precondition failed) error.

Note
The
If-Match
precondition checking for concurrent modifications is currently not supported for the
[membership/members' metadata APIs](https://www.pubnub.com/docs/sdks/rest-api/app-context-membership-introduction.md)
. These APIs also return an
eTag
field in the response body, but that field is not yet checked in the request header.
sub_key
*
Type:
string
Your app's subscribe key from
[Admin Portal](https://admin.pubnub.com)
.
channel
*
Type:
string
The channel ID to perform the operation on. Must not be empty and can contain up to 92 UTF-8 byte sequences.

Prohibited characters
are:
,
,
/
,
\
,
*
,
:
, channel, non-printable ASCII control characters, and Unicode zero.
include
Type:
array
List of additional/complex metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.
auth
Type:
string
String which is either the auth key (Access Manager legacy) or a valid token (
[Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md)
) used to authorize the operation if access control is enabled. Authorization token with permissions to perform the request.
signature
Type:
string
Signature used to verify that the request was signed with the secret key associated with the subscribe key.

If Access Manager is enabled, either a valid authorization token or a signature are required.

Check
[Access Manager documentation](https://www.pubnub.com/docs/sdks/rest-api/access-manager-introduction.md)
for details on how to compute the signature.
timestamp
Type:
integer
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 seconds offset from NTP.

Required if
signature
parameter is supplied.
JSON object with channel metadata to set.
name
Type:
string
The channel name to perform the operation on. Max. 2,048 characters. Must not be empty or consist only of whitespace characters.
≥ 1 chars
Example:
"myChannel1"
description
Type:
string
Description of the channel. Max. 2,048 characters.
type
Type:
string
Channel type. Max. 50 characters.
status
Type:
string
Channel status. Max. 50 characters.
custom
Type:
object
JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.

NOTE
: If you set
custom
fields with integer values, do not specify numbers larger than
9007199254740991
due to
[precision limitations](https://262.ecma-international.org/15.0/index.html?_gl=1*1r821ae*_ga*NjA2NTAwNjA2LjE3MjM2NTY0MDk.*_ga_TDCK4DWEPP*MTcyMzY1NjQwOC4xLjEuMTcyMzY1NzYzMy4wLjAuMA..#sec-number.max_safe_integer)
in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers.
Example Request

```
{
  "name": "My channel",
  "description": "A channel that is mine."
}
```

status
Type:
integer
HTTP status code.
data
Type:
object
Object with channel metadata used in responses.
Example:
{"id":"myChannel3","name":"My channel","description":"A channel that is mine.","updated":"2019-02-20T23:11:20.893Z","eTag":"RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="}
Example Response

```
{
  "status": 200,
  "data": {
    "id": "myChannel3",
    "name": "My channel",
    "description": "A channel that is mine.",
    "updated": "2019-02-20T23:11:20.893Z",
    "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
  }
}
```

status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response

```
{
  "status": 400,
  "error": {
    "message": "Request payload contained invalid input.",
    "source": "metadata",
    "details": [
      {
        "message": "The email must be a valid email address.",
        "location": "uuid.email",
        "locationType": "body"
      }
    ]
  }
}
```

Disabled - The subscribe key doesn't have App Context API enabled.

Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.
status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response
Example
1
Example
2

```
{
  "status": 403,
  "error": {
    "message": "Invalid signature",
    "source": "authz",
    "details": [
      {
        "message": "Client and server produced different signatures for the same inputs.",
        "location": "signature",
        "locationType": "query"
      }
    ]
  }
}
```

status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response

```
{
  "status": 412,
  "error": {
    "message": "Resource already changed by another request since the last retrieval.",
    "source": "metadata"
  }
}
```

status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response

```
{
  "status": 415,
  "error": {
    "message": "Request payload must be in JSON format.",
    "source": "metadata"
  }
}
```

status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response

```
{
  "status": 429,
  "error": {
    "message": "You have exceeded the maximum number of requests per second allowed for your subscribe key.",
    "source": "metadata"
  }
}
```

status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response

```
{
  "status": 500,
  "error": {
    "message": "An unexpected error occurred while processing the request.",
    "source": "metadata"
  }
}
```

status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response

```
{
  "status": 503,
  "error": {
    "message": "The server took longer to respond than the maximum allowed processing time.",
    "source": "metadata"
  }
}
```