Download Codes v3
API for managing download codes. Download codes are redeemable codes that grant access to digital products.
Endpoints
GET /resource/v3/download_codes
Retrieve a list of download codes
Responses
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": 45,
"_uuid": "333c0d12-f5ef-11f0-8321-00505699575c",
"_version": "3.0",
"_links": {},
"download_quota": 10,
"external_identifiers": [
{}
],
"first_download": 1407928793,
"last_download": 1407928836,
"max_lifetime": null,
"product": {
"_id": 23,
"_uuid": "string",
"_links": {},
"title": "Alice in Wonderland",
"eans": [],
"cover_url": "string"
},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"recipient_email": "john.doe@example.com",
"recipient_name": "John Doe",
"request_asset_url": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg",
"require_login": false,
"token": "uxxi4xSg",
"total_downloads": 3,
"unique_downloads": 1,
"url": "https://example.openpublishing.com/free/uxxi4xSg",
"valid_from": 1767222000,
"valid_till": 1767222000
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object"
},
"_pagination": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the download code",
"example": 45
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource",
"example": "333c0d12-f5ef-11f0-8321-00505699575c"
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_links": {
"type": "object"
},
"download_quota": {
"type": "integer",
"description": "Maximum number of times the download code can be used",
"nullable": true,
"example": 10
},
"external_identifiers": {
"type": "array",
"description": "List of external/foreign identifiers, e.g. the id of the download code within an external system. The listed objects are dicts with the values `type` for the type of the identifier and `value` for the identifier itself.",
"items": {
"type": "object"
}
},
"first_download": {
"type": "integer",
"description": "Unix timestamp of the first download using this code",
"nullable": true,
"example": 1407928793
},
"last_download": {
"type": "integer",
"description": "Unix timestamp of the most recent download using this code",
"nullable": true,
"example": 1407928836
},
"max_lifetime": {
"type": "integer",
"description": "Maximum lifetime of the download code in seconds. If null, the code does not expire based on lifetime.",
"nullable": true,
"example": null
},
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Product ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"recipient_email": {
"type": "string",
"description": "Email address of the recipient of the download code",
"nullable": true,
"example": "john.doe@example.com"
},
"recipient_name": {
"type": "string",
"description": "Name of the recipient of the download code",
"nullable": true,
"example": "John Doe"
},
"request_asset_url": {
"type": "string",
"description": "URL to request asset creation for this download code",
"example": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg"
},
"require_login": {
"type": "boolean",
"description": "Indicates whether the recipient must be logged in to use the download code",
"example": false
},
"token": {
"type": "string",
"description": "The unique token string used to redeem the download code",
"example": "uxxi4xSg"
},
"total_downloads": {
"type": "integer",
"description": "Total number of downloads performed using this code",
"example": 3
},
"unique_downloads": {
"type": "integer",
"description": "Number of unique downloads (by distinct users/sessions)",
"example": 1
},
"url": {
"type": "string",
"description": "Public URL where the download code can be redeemed",
"example": "https://example.openpublishing.com/free/uxxi4xSg"
},
"valid_from": {
"type": "integer",
"description": "Start of the validity period in Unix timestamp. If null, the code is valid immediately.",
"nullable": true,
"example": 1767222000
},
"valid_till": {
"type": "integer",
"description": "End of the validity period in Unix timestamp. If null, the code does not expire based on date.",
"nullable": true,
"example": 1767222000
}
},
"required": [
"_id",
"token",
"download_quota"
]
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
POST /resource/v3/download_codes
Create a new download code.
Request body
{
"_id": 45,
"_uuid": "333c0d12-f5ef-11f0-8321-00505699575c",
"_version": "3.0",
"_links": {},
"download_quota": 10,
"external_identifiers": [
{}
],
"first_download": 1407928793,
"last_download": 1407928836,
"max_lifetime": null,
"product": {
"_id": 23,
"_uuid": "string",
"_links": {},
"title": "Alice in Wonderland",
"eans": [],
"cover_url": "string"
},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"recipient_email": "john.doe@example.com",
"recipient_name": "John Doe",
"request_asset_url": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg",
"require_login": false,
"token": "uxxi4xSg",
"total_downloads": 3,
"unique_downloads": 1,
"url": "https://example.openpublishing.com/free/uxxi4xSg",
"valid_from": 1767222000,
"valid_till": 1767222000
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the download code",
"example": 45
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource",
"example": "333c0d12-f5ef-11f0-8321-00505699575c"
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_links": {
"type": "object"
},
"download_quota": {
"type": "integer",
"description": "Maximum number of times the download code can be used",
"nullable": true,
"example": 10
},
"external_identifiers": {
"type": "array",
"description": "List of external/foreign identifiers, e.g. the id of the download code within an external system. The listed objects are dicts with the values `type` for the type of the identifier and `value` for the identifier itself.",
"items": {
"type": "object"
}
},
"first_download": {
"type": "integer",
"description": "Unix timestamp of the first download using this code",
"nullable": true,
"example": 1407928793
},
"last_download": {
"type": "integer",
"description": "Unix timestamp of the most recent download using this code",
"nullable": true,
"example": 1407928836
},
"max_lifetime": {
"type": "integer",
"description": "Maximum lifetime of the download code in seconds. If null, the code does not expire based on lifetime.",
"nullable": true,
"example": null
},
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Product ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"recipient_email": {
"type": "string",
"description": "Email address of the recipient of the download code",
"nullable": true,
"example": "john.doe@example.com"
},
"recipient_name": {
"type": "string",
"description": "Name of the recipient of the download code",
"nullable": true,
"example": "John Doe"
},
"request_asset_url": {
"type": "string",
"description": "URL to request asset creation for this download code",
"example": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg"
},
"require_login": {
"type": "boolean",
"description": "Indicates whether the recipient must be logged in to use the download code",
"example": false
},
"token": {
"type": "string",
"description": "The unique token string used to redeem the download code",
"example": "uxxi4xSg"
},
"total_downloads": {
"type": "integer",
"description": "Total number of downloads performed using this code",
"example": 3
},
"unique_downloads": {
"type": "integer",
"description": "Number of unique downloads (by distinct users/sessions)",
"example": 1
},
"url": {
"type": "string",
"description": "Public URL where the download code can be redeemed",
"example": "https://example.openpublishing.com/free/uxxi4xSg"
},
"valid_from": {
"type": "integer",
"description": "Start of the validity period in Unix timestamp. If null, the code is valid immediately.",
"nullable": true,
"example": 1767222000
},
"valid_till": {
"type": "integer",
"description": "End of the validity period in Unix timestamp. If null, the code does not expire based on date.",
"nullable": true,
"example": 1767222000
}
},
"required": [
"_id",
"token",
"download_quota"
]
}
Responses
{
"_id": 45,
"_uuid": "333c0d12-f5ef-11f0-8321-00505699575c",
"_version": "3.0",
"_links": {},
"download_quota": 10,
"external_identifiers": [
{}
],
"first_download": 1407928793,
"last_download": 1407928836,
"max_lifetime": null,
"product": {
"_id": 23,
"_uuid": "string",
"_links": {},
"title": "Alice in Wonderland",
"eans": [],
"cover_url": "string"
},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"recipient_email": "john.doe@example.com",
"recipient_name": "John Doe",
"request_asset_url": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg",
"require_login": false,
"token": "uxxi4xSg",
"total_downloads": 3,
"unique_downloads": 1,
"url": "https://example.openpublishing.com/free/uxxi4xSg",
"valid_from": 1767222000,
"valid_till": 1767222000
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the download code",
"example": 45
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource",
"example": "333c0d12-f5ef-11f0-8321-00505699575c"
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_links": {
"type": "object"
},
"download_quota": {
"type": "integer",
"description": "Maximum number of times the download code can be used",
"nullable": true,
"example": 10
},
"external_identifiers": {
"type": "array",
"description": "List of external/foreign identifiers, e.g. the id of the download code within an external system. The listed objects are dicts with the values `type` for the type of the identifier and `value` for the identifier itself.",
"items": {
"type": "object"
}
},
"first_download": {
"type": "integer",
"description": "Unix timestamp of the first download using this code",
"nullable": true,
"example": 1407928793
},
"last_download": {
"type": "integer",
"description": "Unix timestamp of the most recent download using this code",
"nullable": true,
"example": 1407928836
},
"max_lifetime": {
"type": "integer",
"description": "Maximum lifetime of the download code in seconds. If null, the code does not expire based on lifetime.",
"nullable": true,
"example": null
},
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Product ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"recipient_email": {
"type": "string",
"description": "Email address of the recipient of the download code",
"nullable": true,
"example": "john.doe@example.com"
},
"recipient_name": {
"type": "string",
"description": "Name of the recipient of the download code",
"nullable": true,
"example": "John Doe"
},
"request_asset_url": {
"type": "string",
"description": "URL to request asset creation for this download code",
"example": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg"
},
"require_login": {
"type": "boolean",
"description": "Indicates whether the recipient must be logged in to use the download code",
"example": false
},
"token": {
"type": "string",
"description": "The unique token string used to redeem the download code",
"example": "uxxi4xSg"
},
"total_downloads": {
"type": "integer",
"description": "Total number of downloads performed using this code",
"example": 3
},
"unique_downloads": {
"type": "integer",
"description": "Number of unique downloads (by distinct users/sessions)",
"example": 1
},
"url": {
"type": "string",
"description": "Public URL where the download code can be redeemed",
"example": "https://example.openpublishing.com/free/uxxi4xSg"
},
"valid_from": {
"type": "integer",
"description": "Start of the validity period in Unix timestamp. If null, the code is valid immediately.",
"nullable": true,
"example": 1767222000
},
"valid_till": {
"type": "integer",
"description": "End of the validity period in Unix timestamp. If null, the code does not expire based on date.",
"nullable": true,
"example": 1767222000
}
},
"required": [
"_id",
"token",
"download_quota"
]
}
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
GET /resource/v3/download_codes/{id}
Retrieve a single download code by ID
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No |
The unique identifier of the download code |
Responses
{
"_id": 45,
"_uuid": "333c0d12-f5ef-11f0-8321-00505699575c",
"_version": "3.0",
"_links": {},
"download_quota": 10,
"external_identifiers": [
{}
],
"first_download": 1407928793,
"last_download": 1407928836,
"max_lifetime": null,
"product": {
"_id": 23,
"_uuid": "string",
"_links": {},
"title": "Alice in Wonderland",
"eans": [],
"cover_url": "string"
},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"recipient_email": "john.doe@example.com",
"recipient_name": "John Doe",
"request_asset_url": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg",
"require_login": false,
"token": "uxxi4xSg",
"total_downloads": 3,
"unique_downloads": 1,
"url": "https://example.openpublishing.com/free/uxxi4xSg",
"valid_from": 1767222000,
"valid_till": 1767222000
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the download code",
"example": 45
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource",
"example": "333c0d12-f5ef-11f0-8321-00505699575c"
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_links": {
"type": "object"
},
"download_quota": {
"type": "integer",
"description": "Maximum number of times the download code can be used",
"nullable": true,
"example": 10
},
"external_identifiers": {
"type": "array",
"description": "List of external/foreign identifiers, e.g. the id of the download code within an external system. The listed objects are dicts with the values `type` for the type of the identifier and `value` for the identifier itself.",
"items": {
"type": "object"
}
},
"first_download": {
"type": "integer",
"description": "Unix timestamp of the first download using this code",
"nullable": true,
"example": 1407928793
},
"last_download": {
"type": "integer",
"description": "Unix timestamp of the most recent download using this code",
"nullable": true,
"example": 1407928836
},
"max_lifetime": {
"type": "integer",
"description": "Maximum lifetime of the download code in seconds. If null, the code does not expire based on lifetime.",
"nullable": true,
"example": null
},
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Product ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"recipient_email": {
"type": "string",
"description": "Email address of the recipient of the download code",
"nullable": true,
"example": "john.doe@example.com"
},
"recipient_name": {
"type": "string",
"description": "Name of the recipient of the download code",
"nullable": true,
"example": "John Doe"
},
"request_asset_url": {
"type": "string",
"description": "URL to request asset creation for this download code",
"example": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg"
},
"require_login": {
"type": "boolean",
"description": "Indicates whether the recipient must be logged in to use the download code",
"example": false
},
"token": {
"type": "string",
"description": "The unique token string used to redeem the download code",
"example": "uxxi4xSg"
},
"total_downloads": {
"type": "integer",
"description": "Total number of downloads performed using this code",
"example": 3
},
"unique_downloads": {
"type": "integer",
"description": "Number of unique downloads (by distinct users/sessions)",
"example": 1
},
"url": {
"type": "string",
"description": "Public URL where the download code can be redeemed",
"example": "https://example.openpublishing.com/free/uxxi4xSg"
},
"valid_from": {
"type": "integer",
"description": "Start of the validity period in Unix timestamp. If null, the code is valid immediately.",
"nullable": true,
"example": 1767222000
},
"valid_till": {
"type": "integer",
"description": "End of the validity period in Unix timestamp. If null, the code does not expire based on date.",
"nullable": true,
"example": 1767222000
}
},
"required": [
"_id",
"token",
"download_quota"
]
}
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
PUT /resource/v3/download_codes/{id}
Update download code.
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No |
The unique identifier of the download code |
Request body
{
"_id": 45,
"_uuid": "333c0d12-f5ef-11f0-8321-00505699575c",
"_version": "3.0",
"_links": {},
"download_quota": 10,
"external_identifiers": [
{}
],
"first_download": 1407928793,
"last_download": 1407928836,
"max_lifetime": null,
"product": {
"_id": 23,
"_uuid": "string",
"_links": {},
"title": "Alice in Wonderland",
"eans": [],
"cover_url": "string"
},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"recipient_email": "john.doe@example.com",
"recipient_name": "John Doe",
"request_asset_url": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg",
"require_login": false,
"token": "uxxi4xSg",
"total_downloads": 3,
"unique_downloads": 1,
"url": "https://example.openpublishing.com/free/uxxi4xSg",
"valid_from": 1767222000,
"valid_till": 1767222000
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the download code",
"example": 45
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource",
"example": "333c0d12-f5ef-11f0-8321-00505699575c"
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_links": {
"type": "object"
},
"download_quota": {
"type": "integer",
"description": "Maximum number of times the download code can be used",
"nullable": true,
"example": 10
},
"external_identifiers": {
"type": "array",
"description": "List of external/foreign identifiers, e.g. the id of the download code within an external system. The listed objects are dicts with the values `type` for the type of the identifier and `value` for the identifier itself.",
"items": {
"type": "object"
}
},
"first_download": {
"type": "integer",
"description": "Unix timestamp of the first download using this code",
"nullable": true,
"example": 1407928793
},
"last_download": {
"type": "integer",
"description": "Unix timestamp of the most recent download using this code",
"nullable": true,
"example": 1407928836
},
"max_lifetime": {
"type": "integer",
"description": "Maximum lifetime of the download code in seconds. If null, the code does not expire based on lifetime.",
"nullable": true,
"example": null
},
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Product ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"recipient_email": {
"type": "string",
"description": "Email address of the recipient of the download code",
"nullable": true,
"example": "john.doe@example.com"
},
"recipient_name": {
"type": "string",
"description": "Name of the recipient of the download code",
"nullable": true,
"example": "John Doe"
},
"request_asset_url": {
"type": "string",
"description": "URL to request asset creation for this download code",
"example": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg"
},
"require_login": {
"type": "boolean",
"description": "Indicates whether the recipient must be logged in to use the download code",
"example": false
},
"token": {
"type": "string",
"description": "The unique token string used to redeem the download code",
"example": "uxxi4xSg"
},
"total_downloads": {
"type": "integer",
"description": "Total number of downloads performed using this code",
"example": 3
},
"unique_downloads": {
"type": "integer",
"description": "Number of unique downloads (by distinct users/sessions)",
"example": 1
},
"url": {
"type": "string",
"description": "Public URL where the download code can be redeemed",
"example": "https://example.openpublishing.com/free/uxxi4xSg"
},
"valid_from": {
"type": "integer",
"description": "Start of the validity period in Unix timestamp. If null, the code is valid immediately.",
"nullable": true,
"example": 1767222000
},
"valid_till": {
"type": "integer",
"description": "End of the validity period in Unix timestamp. If null, the code does not expire based on date.",
"nullable": true,
"example": 1767222000
}
},
"required": [
"_id",
"token",
"download_quota"
]
}
Responses
{
"_id": 45,
"_uuid": "333c0d12-f5ef-11f0-8321-00505699575c",
"_version": "3.0",
"_links": {},
"download_quota": 10,
"external_identifiers": [
{}
],
"first_download": 1407928793,
"last_download": 1407928836,
"max_lifetime": null,
"product": {
"_id": 23,
"_uuid": "string",
"_links": {},
"title": "Alice in Wonderland",
"eans": [],
"cover_url": "string"
},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"recipient_email": "john.doe@example.com",
"recipient_name": "John Doe",
"request_asset_url": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg",
"require_login": false,
"token": "uxxi4xSg",
"total_downloads": 3,
"unique_downloads": 1,
"url": "https://example.openpublishing.com/free/uxxi4xSg",
"valid_from": 1767222000,
"valid_till": 1767222000
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the download code",
"example": 45
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource",
"example": "333c0d12-f5ef-11f0-8321-00505699575c"
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_links": {
"type": "object"
},
"download_quota": {
"type": "integer",
"description": "Maximum number of times the download code can be used",
"nullable": true,
"example": 10
},
"external_identifiers": {
"type": "array",
"description": "List of external/foreign identifiers, e.g. the id of the download code within an external system. The listed objects are dicts with the values `type` for the type of the identifier and `value` for the identifier itself.",
"items": {
"type": "object"
}
},
"first_download": {
"type": "integer",
"description": "Unix timestamp of the first download using this code",
"nullable": true,
"example": 1407928793
},
"last_download": {
"type": "integer",
"description": "Unix timestamp of the most recent download using this code",
"nullable": true,
"example": 1407928836
},
"max_lifetime": {
"type": "integer",
"description": "Maximum lifetime of the download code in seconds. If null, the code does not expire based on lifetime.",
"nullable": true,
"example": null
},
"product": {
"type": "object",
"description": "Reference to product",
"additionalProperties": false,
"nullable": true,
"properties": {
"_id": {
"type": "integer",
"description": "Product ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"title": {
"type": "string",
"description": "Title of product",
"example": "Alice in Wonderland"
},
"eans": {
"type": "array",
"description": "List of the EANs of the product"
},
"cover_url": {
"type": "string",
"description": "URL of cover thumbnail"
}
},
"required": [
"_id"
]
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"recipient_email": {
"type": "string",
"description": "Email address of the recipient of the download code",
"nullable": true,
"example": "john.doe@example.com"
},
"recipient_name": {
"type": "string",
"description": "Name of the recipient of the download code",
"nullable": true,
"example": "John Doe"
},
"request_asset_url": {
"type": "string",
"description": "URL to request asset creation for this download code",
"example": "https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg"
},
"require_login": {
"type": "boolean",
"description": "Indicates whether the recipient must be logged in to use the download code",
"example": false
},
"token": {
"type": "string",
"description": "The unique token string used to redeem the download code",
"example": "uxxi4xSg"
},
"total_downloads": {
"type": "integer",
"description": "Total number of downloads performed using this code",
"example": 3
},
"unique_downloads": {
"type": "integer",
"description": "Number of unique downloads (by distinct users/sessions)",
"example": 1
},
"url": {
"type": "string",
"description": "Public URL where the download code can be redeemed",
"example": "https://example.openpublishing.com/free/uxxi4xSg"
},
"valid_from": {
"type": "integer",
"description": "Start of the validity period in Unix timestamp. If null, the code is valid immediately.",
"nullable": true,
"example": 1767222000
},
"valid_till": {
"type": "integer",
"description": "End of the validity period in Unix timestamp. If null, the code does not expire based on date.",
"nullable": true,
"example": 1767222000
}
},
"required": [
"_id",
"token",
"download_quota"
]
}
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
DELETE /resource/v3/download_codes/{id}
Delete download code by ID
Input parameters
Path parameters
| Parameter | Type | Default | Nullable | Description |
|---|---|---|---|---|
id |
string | No |
The unique identifier of the download code |
Responses
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
{
"errors": [
{
"_id": "string",
"stack_trace": [
"string"
],
"message": "string",
"vars": {}
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"description": "List of errors occurred",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"_id",
"message",
"stack_trace",
"vars"
],
"properties": {
"_id": {
"type": "string",
"description": "The identifier of the error"
},
"stack_trace": {
"type": "array",
"description": "A stacktrace of the error occurred. Only for testing systems.",
"items": {
"type": "string"
}
},
"message": {
"type": "string",
"description": "A translated message of the error"
},
"vars": {
"type": "object",
"description": "A dict containing additional values of the context of the error."
}
}
}
}
}
}
Schemas
Download Code
| Name | Type | Description | Example |
|---|---|---|---|
_id |
integer |
Unique identifier for the download code |
45 |
_links |
object | ||
_uuid |
string |
ID of resource in V4 version of resource |
333c0d12-f5ef-11f0-8321-00505699575c |
_version |
string |
API Version |
3.0 |
download_quota |
integer| null |
Maximum number of times the download code can be used |
10 |
external_identifiers |
Array<object> |
List of external/foreign identifiers, e.g. the id of the download code within an external system. The listed objects are dicts with the values |
|
first_download |
integer| null |
Unix timestamp of the first download using this code |
1407928793 |
last_download |
integer| null |
Unix timestamp of the most recent download using this code |
1407928836 |
max_lifetime |
integer| null |
Maximum lifetime of the download code in seconds. If null, the code does not expire based on lifetime. |
|
product |
Properties: _id, _uuid, _links, title, eans, cover_url| null |
Reference to product |
|
product._id |
integer |
Product ID |
23 |
product._uuid |
string |
ID of resource in V4 version of resource |
|
product._links |
object | ||
product.title |
string |
Title of product |
Alice in Wonderland |
product.eans |
Array<> |
List of the EANs of the product |
|
product.cover_url |
string |
URL of cover thumbnail |
|
realm |
Properties: _id, _uuid, _links, name, screenname |
Reference to realm which owns this object |
|
realm._id |
integer |
Realm ID |
23 |
realm._uuid |
string |
ID of resource in V4 version of resource |
|
realm._links |
object | ||
realm.name |
string |
Name of the realm |
xyzpublishing |
realm.screenname |
string |
Screenname of the realm |
XYZ Publishing |
recipient_email |
string| null |
Email address of the recipient of the download code |
john.doe@example.com |
recipient_name |
string| null |
Name of the recipient of the download code |
John Doe |
request_asset_url |
string |
URL to request asset creation for this download code |
https://example.openpublishing.com/rpc/v2/download_code?method=request_asset_creation&token=uxxi4xSg |
require_login |
boolean |
Indicates whether the recipient must be logged in to use the download code |
false |
token |
string |
The unique token string used to redeem the download code |
uxxi4xSg |
total_downloads |
integer |
Total number of downloads performed using this code |
3 |
unique_downloads |
integer |
Number of unique downloads (by distinct users/sessions) |
1 |
url |
string |
Public URL where the download code can be redeemed |
https://example.openpublishing.com/free/uxxi4xSg |
valid_from |
integer| null |
Start of the validity period in Unix timestamp. If null, the code is valid immediately. |
1767222000 |
valid_till |
integer| null |
End of the validity period in Unix timestamp. If null, the code does not expire based on date. |
1767222000 |