Skip to main content

Publications

The available operations are: Create, Retrieve, Update and Delete.

info

The query parameter user_token is required and needs to be present in any requests, regardless the operation.

Example endpoint: https://your-store.com/integration-api/v1/dashboard/issues/?user_token=api-77d0b904-3b46-4e1a-8fde-2596375270b8

Header Required#

To make sure the requests gets processed succesfully, you need to ensure headers contain:

keyvalue
Content-typeapplication/json
Acceptapplication/json

Failing to do so will generate less useful error responses or redirects.

Create#

The API endpoint expects a POST request to: https://your-store.com/integration-api/v1/dashboard/issues/

The body of the requests needs to contain this parameters:

parametertypedefaultnotes
namestring
publication_datestringformat: Y-m-d 2018-07-27.
extensionstringAccept only 'mpga', 'mp3', 'pdf' or 'epub'
file_urlurl, stringEPUB or PDF, up to 256mb
external_idstringnullRecommended, since it's the field you'll need to use for any other operation or when using other APIs like Reading Permissions.
freebooleanfalseOptional

If you need to set taxonomies terms, you need to use the taxonomy slug as the key name and the values in a plain array list. For the available taxonomies slugs check the code example.

<?php
// Example in PHP using Laravel's Http
use Illuminate\Support\Facades\Http;
$response = Http::post('https://your-store.com/integration-api/v1/dashboard/issues/?user_token=api-77d0b904-3b46-4e1a-8fde-2596375270b8', [
'publication_date' => '2021-03-17',
'name' => 'The Computing Machine',
'description' => 'The description of the publication...',
'free' => 0,
'extension' => 'pdf',
'file_url' =>
'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
// optional, use it if you need to set taxonomies terms and use only the specific taxonomies you want to set
'collection' => ['The classics'],
'author' => ['Grace Hopper', 'Alan Turing'],
'country' => ['Finland'],
'category' => ['Hardware meets software'],
'publisher' => ['publica.la'],
'keyword' => ['API', 'book'],
]);
dd($response->status(), $response->body());
?>

Responses

codewhat happenednote
201Created successfullyObject returned with created issue
422Validation error

Retrieve#

The API endpoint expects a GET request to: https://your-store.com/integration-api/v1/dashboard/issues

To GET especific publication data.

optiontypeendpoint
issue_idintegerhttps://your-store.com/integration-api/v1/dashboard/issues/{issue_id}
like_namestring, query parameterhttps://your-store.com/integration-api/v1/dashboard/issues/?like_name=The%20Computing%20Machine

Responses

The response is a JSON with a list of publications paginated by 15 items.

codewhat happenednote
200SuccessObject returned
404No query result
Object returned example
{
"CODE": "success",
"data": {
"paginator": {
"current_page": 1,
"data": [
{
"id": 468166,
"external_id": "9781496822482",
"version": 1,
"marketplace": 1,
"license": {
"ppu": false,
"retail": true
},
"discount": 50,
"file_type": "epub",
"lang": "en",
"user_id": 47635,
"medusa_automation_id": null,
"name": "Conversations with Donald Hall",
"slug": "conversations-with-donald-hall",
"conversion_status": "done",
"conversion_settings": {
"PdfSplitInPages": {
"pagesPerGroup": null,
"concurrentWorkerRequests": null
}
},
"conversion_details": null,
"published_at": {
"timestamp": 1616122800,
"date": "2021-03-19 00:00:00",
"timezone": "America/Argentina/Buenos_Aires"
},
"bucket_domain": "storage.publica.la",
"cover_image_path": "https://your-store.com/publicala/issues/2021/03/ZotqenpMS797S5wS/41a3c9c7-5f9f-4db5-bb6c-714865d2fdbd_cover.jpg",
"number_of_pages": null,
"notifies_users": null,
"notification_text": null,
"notified_users_at": null,
"medusa_automation_status": null,
"created_at": "2021-03-06 06:00:51",
"ti_id": 531184,
"ti_tenant_id": 627,
"ti_issue_id": 468166,
"ti_license": "retail",
"ti_withdrawn": 0,
"ti_free": 0,
"ti_free_to": null,
"ti_require_login": null,
"ti_preview": 0,
"ti_require_login_for_preview": 0,
"ti_private_material": null,
"ti_published_at": "2021-03-19 03:00:00",
"ti_created_at": "2021-03-24 13:46:37",
"ti_updated_at": "2021-03-24 16:10:15",
"ti_deleted_at": null,
"cover": "https://your-store.com/publicala/issues/2021/03/ZotqenpMS797S5wS/41a3c9c7-5f9f-4db5-bb6c-714865d2fdbd_cover.jpg",
"url": "https://your-store.com/reader/conversations-with-donald-hall",
"share_url": "https://your-store.com/library/publication/conversations-with-donald-hall",
"public_file_url": "https://your-store.com/api/v1/dashboard/issues/468166/temp-public-url",
"current_session_limit": 0,
"can_be_removed_from_inventory": true,
"notes_count": 0,
"description": "<i>Conversations with Donald Hall</i> offers a unique glimp...",
"description_with_html": "<i>Conversations with Donald Hall</i> offers a unique glimp...",
"is_owned_by_current_tenant": true,
"free": false,
"free_to": null,
"prices": {
"USD": 25
},
"preview": true,
"private_material": null,
"publication_date": {
"timestamp": 1616122800,
"date": "2021-03-19 00:00:00",
"timezone": "America/Argentina/Buenos_Aires"
},
"require_login": null,
"require_login_for_preview": 0,
"conversion_status_progress": null,
"published_at_utc": "2021-03-19 03:00:00",
"price_morph": [
{
"tenant_id": 1,
"id": 461064,
"priceable_type": "issue",
"priceable_id": 468166,
"type": "single",
"country_code": null,
"currency_id": "USD",
"amount_in_cents": 2500,
"created_at": "2021-03-06 06:00:52",
"updated_at": "2021-03-06 06:00:52",
"deleted_at": null
}
],
"sessions": null,
"issue_description": {
"issue_id": 468166,
"description": "<i>Conversations with Donald Hall</i> offers a unique glimp..."
}
},
{
...
},
],
"first_page_url": "https://your-store.com/integration-api/v1/dashboard/issues?page=1",
"from": 1,
"last_page": 6,
"last_page_url": "https://your-store.com/integration-api/v1/dashboard/issues?page=6",
"links": [
{
"url": null,
"label": "&laquo; Previous",
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=1",
"label": 1,
"active": true
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=2",
"label": 2,
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=3",
"label": 3,
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=4",
"label": 4,
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=5",
"label": 5,
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=6",
"label": 6,
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=2",
"label": "Next &raquo;",
"active": false
}
],
"next_page_url": "https://your-store.com/integration-api/v1/dashboard/issues?page=2",
"path": "https://your-store.com/integration-api/v1/dashboard/issues",
"per_page": 15,
"prev_page_url": null,
"to": 15,
"total": 82
},
"reached_issues_limit": false,
"reached_free_issues_limit": false
}
}

Update#

The API endpoint expects a PUT request to: https://your-store.com/integration-api/v1/dashboard/issues/{issue_id}

parametertypenotes
namestringrequired
publication_datestringrequired. Format: Y-m-d 2018-07-27.
descriptionnullable, string, max:13000
private_materialnullable, string, max:5000
freenullable, boolean
free_tostringFormat: Y-m-d 2018-07-27
require_loginnullableboolean
external_idnullable, string, uniqueRecommended, since it's the field you'll need to use for any other operation or when using other APIs like Reading Permissions.

When updating a publication, make sure to send all the desired final taxonomies and terms. If a publication already has a term in a specific taxonomy and you just want to add a second one, you still need to send both. Ex. If you need to add a new author to the list 'Grace Hopper', 'Alan Turing', you will send:

// to add
'author': ['Grace Hopper', 'Alan Turing', 'New Author'],

If you need remove 'Grace Hopper', you will just send the one that stays:

// to remove
'author': ['Alan Turing'],
<?php
// Example in PHP using Laravel's Http
use Illuminate\Support\Facades\Http;
$response = Http::put('https://your-store.com/integration-api/v1/dashboard/issues/{issue_id}?user_token=api-77d0b904-3b46-4e1a-8fde-2596375270b8', [
'publication_date' => '2021-03-17',
'name' => 'The Computing Machine two',
'description' => 'The description of the publication...',
'private_material' => null,
'free' => 0,
'free_to' => '2021-04-11',
'require_login' => 1,
'external_id' => 12345098
]);
dd($response->status(), $response->body());
?>

Responses

codewhat happenednote
204Updated successfullyEmpty data is returned
422Validation errorValidation message ir returned

Delete#

The API endpoint expects a DELETE request to: https://your-store.com/integration-api/v1/dashboard/issues/

optiontypeendpoint
issue_idintegerhttps://your-store.com/integration-api/v1/dashboard/issues/{issue_id}
external_idintegerhttps://your-store.com/integration-api/v1/dashboard/issues/{external_id}

Responses

codewhat happenednote
200Deleted successfullyObject returned with deleted issue
404Not found to delete