Content Library

Content Library: List

Retrieve Content Library items for an account with Content Library enabled. API keys and OAuth access tokens act as the API app and must not specify userId. User principal tokens require Content Library view permission; results are limited to the user's permitted entity, folder, and label scopes. User principal tokens also require view permission for Content Library and the Post Calendar.

path Parameters

accountId

required

string

query Parameters

v required	string A date in `YYYYMMDD` format.
search	string
searchIn	string Comma-separated fields to search. Supported values are title, caption, and tags; text is an alias for caption. Values are case-insensitive. Unknown fields are ignored. If no recognized fields remain, all three fields are searched.
page	integer <int32> [ -2147483648 .. 2147483647 ] Default: 1 The page number as a signed 32-bit integer. Values below 1 are treated as 1.
pageSize	integer <int32> [ -2147483648 .. 2147483647 ] Default: 20 The number of items per page as a signed 32-bit integer. Values above 100 use 100; values below 1 use 20.
includeExpired	boolean Default: false Whether to include expired items as well as live items.
sortBy	string Default: "createdAt" The sort field. Recognized values are createdAt, updatedAt, and title. Values are case-sensitive. Other values use createdAt.
sortDirection	string Default: "desc" The sort direction. The value asc is case-insensitive and selects ascending order. All other values use descending order.

Responses

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"items": [{"id": "string",
"title": "string",
"caption": "string",
"tags": ["string"
],
"entityIds": ["string"
],
"publisherIds": ["string"
],
"draftPostRequestJson": "string",
"createdBy": {"type": "USER",
"id": "string"
},
"updatedBy": {"type": "USER",
"id": "string"
},
"createdByUserId": "string",
"updatedByUserId": "string",
"live": true,
"expiredAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"meta": {"page": 0,
"all_items": 0
}
}
}

Content Library: Create

Create a Content Library item in an account with Content Library enabled. The authenticated caller is recorded as the actor. API keys and OAuth access tokens act as the API app and must not specify userId. User principal tokens require Content Library manage permission for all selected entity, folder, and label scopes, including includeAllEntities. Publisher content is validated before the item is saved. User principal tokens also require view permission for Content Library and the Post Calendar.

path Parameters

accountId

required

string

query Parameters

required

string

A date in YYYYMMDD format.

Request Body schema: application/json

Any of

required	(object or object) or (object or null) The structured draft post request. Supply this or draftPostRequestJson. A non-null value takes precedence if both are supplied. A null value uses draftPostRequestJson instead. Supply one post request object, or an object with a nonempty createPostRequests array of post request objects. Each request must contain a nonempty numeric publisherIds array and valid content for its publishers. Draft entityIds arrays have a limit of 500 entries. Optional modificationProhibited is an array of unique values from MEDIA and CONTENT. Targeting can use entityIds, folderIds, labelIds, and includeAllEntities, subject to the caller's permissions.
title required	string non-empty [^\u0009-\u000D\u001C-\u0020\u1680\u2000-\u20... A nonblank title used to identify the library item.
caption	string or null The social post copy stored in the library item. Omitted or null values use an empty string. For a draft that contains only Story posts, omit this field or leave it blank. Story variants must also have blank postText.
tags	Array of strings or null Tags used to organize the library item. Each tag is trimmed and must contain 1 to 20 ASCII letters, numbers, underscores, or hyphens. Duplicate tags are removed. At most 15 distinct tags are allowed. Omitted or null values use no tags.
required	Array of strings or integers <= 500 items The entities associated with the library item. An empty array is allowed. IDs can be supplied as signed 64-bit integer values or decimal strings.
required	Array of strings or integers non-empty unique Unique publisher IDs from 1 to 2147483647, supplied as integer values or decimal strings. IDs must be unique after conversion to integers. These IDs must match the numeric publisherIds in the draft. Each publisher must occur in exactly one draft variant.
draftPostRequestJson	string or null A JSON string that encodes the ContentLibraryDraft object accepted by draftPostRequest, including its post variants and publisher-specific fields. Supply this or a non-null draftPostRequest. A null value is allowed only when draftPostRequest supplies the object.
	(string or null) or string The time at which the library item expires. A nonblank timestamp must be in the future for create and update requests. Omitted or null values use expiresAt when supplied. If both fields are omitted or null, or the selected value is blank, the item has no expiration. A non-null expiredAt takes precedence over expiresAt, even if it is blank.
	(string or null) or string An alias for expiredAt. Used only when expiredAt is omitted or null.

Responses

Request samples

Payload

Content type

application/json

{"draftPostRequestJson": "string",
"title": "string",
"caption": "string",
"tags": ["string"
],
"entityIds": ["string"
],
"publisherIds": ["string"
],
"draftPostRequest": {"createPostRequests": [{"publisherIds": [559
],
"postText": "A reusable post"
},
{"publisherIds": [953
],
"media": [{"url": "https://example.com/photo.jpg",
"type": "PHOTO"
}
]
}
]
},
"expiredAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z"
}

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"item": {"id": "string",
"title": "string",
"caption": "string",
"tags": ["string"
],
"entityIds": ["string"
],
"publisherIds": ["string"
],
"draftPostRequestJson": "string",
"createdBy": {"type": "USER",
"id": "string"
},
"updatedBy": {"type": "USER",
"id": "string"
},
"createdByUserId": "string",
"updatedByUserId": "string",
"live": true,
"expiredAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
}

Content Library Tags: List

Retrieve distinct tags used by live Content Library items in an account with Content Library enabled. API keys and OAuth access tokens act as the API app and must not specify userId. User principal tokens require Content Library view permission; tags are limited to items in the user's permitted entity, folder, and label scopes. User principal tokens also require view permission for Content Library and the Post Calendar.

path Parameters

accountId

required

string

query Parameters

required

string

A date in YYYYMMDD format.

Responses

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"tags": ["string"
]
}
}

Content Library: Get

Retrieve a live or expired Content Library item from an account with Content Library enabled. API keys and OAuth access tokens act as the API app and must not specify userId. User principal tokens require Content Library view permission for the item. User principal tokens also require view permission for Content Library and the Post Calendar.

path Parameters

accountId required	string
id required	string^(?:-?0*(?:[0-9]{1,18}\|[0-8][0-9]{18}\|9[0-1][... The ID of the Content Library item as a signed 64-bit decimal string.

query Parameters

required

string

A date in YYYYMMDD format.

Responses

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"item": {"id": "string",
"title": "string",
"caption": "string",
"tags": ["string"
],
"entityIds": ["string"
],
"publisherIds": ["string"
],
"draftPostRequestJson": "string",
"createdBy": {"type": "USER",
"id": "string"
},
"updatedBy": {"type": "USER",
"id": "string"
},
"createdByUserId": "string",
"updatedByUserId": "string",
"live": true,
"expiredAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
}

Content Library: Update

Replace the content of a Content Library item in an account with Content Library enabled. Supply all required input fields and the updatedAt value from the most recent item response. A stale updatedAt value causes the update to fail; retrieve the item again before retrying. Omitted caption and tags are cleared; an omitted expiration removes the expiration. API keys and OAuth access tokens act as the API app and must not specify userId. User principal tokens require manage permission for both the existing item and all selected entity, folder, and label scopes. Publisher content is validated before the item is saved. User principal tokens also require view permission for Content Library and the Post Calendar.

path Parameters

accountId required	string
id required	string^(?:-?0*(?:[0-9]{1,18}\|[0-8][0-9]{18}\|9[0-1][... The ID of the Content Library item as a signed 64-bit decimal string.

query Parameters

required

string

A date in YYYYMMDD format.

Request Body schema: application/json

Any of

required	(object or object) or (object or null) The structured draft post request. Supply this or draftPostRequestJson. A non-null value takes precedence if both are supplied. A null value uses draftPostRequestJson instead. Supply one post request object, or an object with a nonempty createPostRequests array of post request objects. Each request must contain a nonempty numeric publisherIds array and valid content for its publishers. Draft entityIds arrays have a limit of 500 entries. Optional modificationProhibited is an array of unique values from MEDIA and CONTENT. Targeting can use entityIds, folderIds, labelIds, and includeAllEntities, subject to the caller's permissions.
title required	string non-empty [^\u0009-\u000D\u001C-\u0020\u1680\u2000-\u20... A nonblank title used to identify the library item.
caption	string or null The social post copy stored in the library item. Omitted or null values use an empty string. For a draft that contains only Story posts, omit this field or leave it blank. Story variants must also have blank postText.
tags	Array of strings or null Tags used to organize the library item. Each tag is trimmed and must contain 1 to 20 ASCII letters, numbers, underscores, or hyphens. Duplicate tags are removed. At most 15 distinct tags are allowed. Omitted or null values use no tags.
required	Array of strings or integers <= 500 items The entities associated with the library item. An empty array is allowed. IDs can be supplied as signed 64-bit integer values or decimal strings.
required	Array of strings or integers non-empty unique Unique publisher IDs from 1 to 2147483647, supplied as integer values or decimal strings. IDs must be unique after conversion to integers. These IDs must match the numeric publisherIds in the draft. Each publisher must occur in exactly one draft variant.
draftPostRequestJson	string or null A JSON string that encodes the ContentLibraryDraft object accepted by draftPostRequest, including its post variants and publisher-specific fields. Supply this or a non-null draftPostRequest. A null value is allowed only when draftPostRequest supplies the object.
	(string or null) or string The time at which the library item expires. A nonblank timestamp must be in the future for create and update requests. Omitted or null values use expiresAt when supplied. If both fields are omitted or null, or the selected value is blank, the item has no expiration. A non-null expiredAt takes precedence over expiresAt, even if it is blank.
	(string or null) or string An alias for expiredAt. Used only when expiredAt is omitted or null.
updatedAt required	string <date-time> The updatedAt value from the most recent item response.

Responses

Request samples

Payload

Content type

application/json

{"draftPostRequestJson": "string",
"title": "string",
"caption": "string",
"tags": ["string"
],
"entityIds": ["string"
],
"publisherIds": ["string"
],
"draftPostRequest": {"createPostRequests": [{"publisherIds": [559
],
"postText": "A reusable post"
},
{"publisherIds": [953
],
"media": [{"url": "https://example.com/photo.jpg",
"type": "PHOTO"
}
]
}
]
},
"expiredAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"item": {"id": "string",
"title": "string",
"caption": "string",
"tags": ["string"
],
"entityIds": ["string"
],
"publisherIds": ["string"
],
"draftPostRequestJson": "string",
"createdBy": {"type": "USER",
"id": "string"
},
"updatedBy": {"type": "USER",
"id": "string"
},
"createdByUserId": "string",
"updatedByUserId": "string",
"live": true,
"expiredAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
}

Content Library: Expire

Expire a Content Library item without deleting it permanently. The account must have Content Library enabled. API keys and OAuth access tokens act as the API app and must not specify userId. User principal tokens require Content Library expire permission for the item. With no expiration in the body, the item expires immediately. A supplied expiration must not be in the future. User principal tokens also require view permission for Content Library and the Post Calendar.

path Parameters

accountId required	string
id required	string^(?:-?0*(?:[0-9]{1,18}\|[0-8][0-9]{18}\|9[0-1][... The ID of the Content Library item as a signed 64-bit decimal string.

query Parameters

required

string

A date in YYYYMMDD format.

Request Body schema: application/json

	(string or null) or string The expiration time, at or before the current time. Omitted or null values use expiresAt when supplied. If both fields are omitted or null, or the selected value is blank, the item expires immediately. A non-null expiredAt takes precedence over expiresAt, even if it is blank.
	(string or null) or string An alias for expiredAt. Used only when expiredAt is omitted or null.

Responses

Request samples

Payload

Content type

application/json

{"expiredAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z"
}

Response samples

200
default

Content type

application/json

{"meta": {"uuid": "4f72b877-e2d0-4de4-9324-b9cf2c03e1a0"
},
"response": {"item": {"id": "string",
"title": "string",
"caption": "string",
"tags": ["string"
],
"entityIds": ["string"
],
"publisherIds": ["string"
],
"draftPostRequestJson": "string",
"createdBy": {"type": "USER",
"id": "string"
},
"updatedBy": {"type": "USER",
"id": "string"
},
"createdByUserId": "string",
"updatedByUserId": "string",
"live": true,
"expiredAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
}