# Issues

API for managing issues

## List Issues

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id`

This endpoint **returns** a list of all `issues` that belong to the magazine

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

#### Query Parameters

| Name         | Type   | Description          |
| ------------ | ------ | -------------------- |
| screen\_type | String | Screen Type          |
| source       | String | Source type of issue |
| url\_scheme  | String |                      |
| generator    | String | Generator            |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Welcome to MagLoft",
  "info": null,
  "hpub": null,
  "source_file": null,
  "source": "typeloft",
  "unlock_type": "free",
  "hide_locked": false,
  "categories": [
    "Sports",
    "Business",
    "Politics"
  ],
  "category_ids": [
    1,
    2,
    3
  ],
  "classifications": [
    "Sports",
    "Business",
    "Politics"
  ],
  "classification_ids": [
    1,
    2,
    3
  ],
  "product_id": "purchase.issue_123456789",
  "product_id_apple": null,
  "product_id_google": null,
  "product_id_amazon": null,
  "screen_type": "issue",
  "publication_id": null,
  "coupon_code": null,
  "dirty": false,
  "user_id": null,
  "custom_stylesheet": null,
  "custom_data": null,
  "price_tier": null,
  "cover": null,
  "generator": "pdfix"
}
```

{% endtab %}
{% endtabs %}

## Retrieve paginated list of issues

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/page/:page`

This endpoint **returns** a page list of all `issues` that belong to the magazine

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| page    | Integer | The page number to list                         |

#### Query Parameters

| Name       | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| per\_page  | Integer | Number of items to show per page         |
| order\_by  | Symbol  | Field to sort results by                 |
| order\_dir | Symbol  | Direction (asc, desc) to sort results by |
| filter     | String  | Text filter to search results by         |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "total": 1,
  "page": 1,
  "records": [
    {
      "id": 1234,
      "title": "Welcome to MagLoft",
      "info": null,
      "hpub": null,
      "source_file": null,
      "source": "typeloft",
      "unlock_type": "free",
      "hide_locked": false,
      "categories": [
        "Sports",
        "Business",
        "Politics"
      ],
      "category_ids": [
        1,
        2,
        3
      ],
      "classifications": [
        "Sports",
        "Business",
        "Politics"
      ],
      "classification_ids": [
        1,
        2,
        3
      ],
      "product_id": "purchase.issue_123456789",
      "product_id_apple": null,
      "product_id_google": null,
      "product_id_amazon": null,
      "screen_type": "issue",
      "publication_id": null,
      "coupon_code": null,
      "dirty": false,
      "user_id": null,
      "custom_stylesheet": null,
      "custom_data": null,
      "price_tier": null,
      "cover": null,
      "generator": "pdfix"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Get Issue

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id`

This endpoint **returns** a specific `issue` by `id`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Welcome to MagLoft",
  "info": null,
  "hpub": null,
  "source_file": null,
  "source": "typeloft",
  "unlock_type": "free",
  "hide_locked": false,
  "categories": [
    "Sports",
    "Business",
    "Politics"
  ],
  "category_ids": [
    1,
    2,
    3
  ],
  "classifications": [
    "Sports",
    "Business",
    "Politics"
  ],
  "classification_ids": [
    1,
    2,
    3
  ],
  "product_id": "purchase.issue_123456789",
  "product_id_apple": null,
  "product_id_google": null,
  "product_id_amazon": null,
  "screen_type": "issue",
  "publication_id": null,
  "coupon_code": null,
  "dirty": false,
  "user_id": null,
  "custom_stylesheet": null,
  "custom_data": null,
  "price_tier": null,
  "cover": null,
  "generator": "pdfix"
}
```

{% endtab %}
{% endtabs %}

## Download Issue

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id/download`

This endpoint **redirects** to a specific `issue` HPUB url

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

{% tabs %}
{% tab title="200 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}

## Download a specific issue source

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id/source`

This endpoint **redirects** to a specific `issue` source file url

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

{% tabs %}
{% tab title="200 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}

## Create an Issue

<mark style="color:green;">`POST`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id`

This endpoint **creates** a new `issue` and **returns** the saved `issue`

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

#### Request Body

| Name                | Type                       | Description               |
| ------------------- | -------------------------- | ------------------------- |
| user\_id            | Integer                    | Issue User ID             |
| title               | String                     | Issue Title               |
| info                | String                     | Issue information         |
| date                | String                     | Issue publish date        |
| product\_id         | String                     | Issue product id          |
| product\_id\_apple  | String                     | Issue product id (Apple)  |
| product\_id\_google | String                     | Issue product id (Google) |
| product\_id\_amazon | String                     | Issue product id (Amazon) |
| unlock\_type        | String                     | Unlock Type               |
| hide\_locked        | Virtus::Attribute::Boolean | Hide if Locked            |
| price\_tier         | Integer                    | Issue price tier          |
| design\_id          | Integer                    | Issue typeloft theme id   |
| cover               | String                     | Issue Cover               |
| hpub                | String                     | Issue HPUB Path           |
| source\_file        | String                     | Issue Source File         |
| source              | String                     | Source type of issue      |
| category\_ids       | Array                      | Issue category IDs        |
| classification\_ids | Array                      | Issue classification IDs  |
| properties          | Hash                       | Issue properties          |
| status              | Symbol                     |                           |
| create\_pages       | Virtus::Attribute::Boolean |                           |
| publish             | Virtus::Attribute::Boolean |                           |
| screen\_type        | String                     |                           |
| file\_size          | Integer                    |                           |
| generator           | String                     |                           |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Welcome to MagLoft",
  "info": null,
  "hpub": null,
  "source_file": null,
  "source": "typeloft",
  "unlock_type": "free",
  "hide_locked": false,
  "categories": [
    "Sports",
    "Business",
    "Politics"
  ],
  "category_ids": [
    1,
    2,
    3
  ],
  "classifications": [
    "Sports",
    "Business",
    "Politics"
  ],
  "classification_ids": [
    1,
    2,
    3
  ],
  "product_id": "purchase.issue_123456789",
  "product_id_apple": null,
  "product_id_google": null,
  "product_id_amazon": null,
  "screen_type": "issue",
  "publication_id": null,
  "coupon_code": null,
  "dirty": false,
  "user_id": null,
  "custom_stylesheet": null,
  "custom_data": null,
  "price_tier": null,
  "cover": null,
  "generator": "pdfix"
}
```

{% endtab %}
{% endtabs %}

## Update an Issue

<mark style="color:orange;">`PUT`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id`

This endpoint **updates** a specific `issue` by `id` and **returns** the updated `issue`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

#### Request Body

| Name                                 | Type                       | Description               |
| ------------------------------------ | -------------------------- | ------------------------- |
| title                                | String                     | Issue Title               |
| info                                 | String                     | Issue information         |
| date                                 | String                     | Issue publish date        |
| product\_id                          | String                     | Issue product id          |
| product\_id\_apple                   | String                     | Issue product id (Apple)  |
| product\_id\_google                  | String                     | Issue product id (Google) |
| product\_id\_amazon                  | String                     | Issue product id (Amazon) |
| unlock\_type                         | String                     | Unlock Type               |
| hide\_locked                         | Virtus::Attribute::Boolean | Hide if Locked            |
| price\_tier                          | Integer                    | Issue price tier          |
| cover                                | String                     | Issue Cover               |
| hpub                                 | String                     | Issue HPUB Path           |
| source\_file                         | String                     | Issue Source File         |
| source                               | String                     | Source type of issue      |
| category\_ids                        | Array                      | Issue category IDs        |
| classification\_ids                  | Array                      | Issue classification IDs  |
| status                               | Symbol                     |                           |
| jid\_status                          | Symbol                     |                           |
| custom\_data                         | Hash                       | Custom Data Hash          |
| custom\_data\[language]              | String                     |                           |
| custom\_data\[copy\_of]              | String                     |                           |
| screenshots                          | \[String]                  |                           |
| properties                           | Hash                       | Issue properties          |
| properties\[page\_turn\_tap]         | Virtus::Attribute::Boolean |                           |
| properties\[vertical\_bounce]        | Virtus::Attribute::Boolean |                           |
| properties\[max\_zoom\_level]        | Float                      |                           |
| properties\[dual\_spread]            | Virtus::Attribute::Boolean |                           |
| properties\[dual\_spread\_cover]     | Virtus::Attribute::Boolean |                           |
| properties\[default\_orientation]    | String                     |                           |
| properties\[orientation\_phone]      | String                     |                           |
| properties\[orientation\_tablet]     | String                     |                           |
| properties\[converted\_to\_typeloft] | Virtus::Attribute::Boolean |                           |
| properties\[reverse\_page\_order]    | Virtus::Attribute::Boolean |                           |
| properties\[link\_style]             | String                     |                           |
| properties\[allowed\_devices]        | \[String]                  |                           |
| properties\[allowed\_platforms]      | \[String]                  |                           |
| properties\[navigator]               | Virtus::Attribute::Boolean |                           |
| properties\[cover\_colors]           | \[String]                  |                           |
| properties\[features]                | \[String]                  |                           |
| properties\[web\_url]                | String                     |                           |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Welcome to MagLoft",
  "info": null,
  "hpub": null,
  "source_file": null,
  "source": "typeloft",
  "unlock_type": "free",
  "hide_locked": false,
  "categories": [
    "Sports",
    "Business",
    "Politics"
  ],
  "category_ids": [
    1,
    2,
    3
  ],
  "classifications": [
    "Sports",
    "Business",
    "Politics"
  ],
  "classification_ids": [
    1,
    2,
    3
  ],
  "product_id": "purchase.issue_123456789",
  "product_id_apple": null,
  "product_id_google": null,
  "product_id_amazon": null,
  "screen_type": "issue",
  "publication_id": null,
  "coupon_code": null,
  "dirty": false,
  "user_id": null,
  "custom_stylesheet": null,
  "custom_data": null,
  "price_tier": null,
  "cover": null,
  "generator": "pdfix"
}
```

{% endtab %}
{% endtabs %}

## Clone an Issue

<mark style="color:green;">`POST`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id/clone/:magazine_id`

This endpoint **creates** a new `issue` by cloning an existing `issue` and **returns** the saved `issue`

#### Path Parameters

| Name         | Type    | Description                                     |
| ------------ | ------- | ----------------------------------------------- |
| app\_id      | String  | App ID (Publication) to scope this request for. |
| id           | Integer | Issue ID                                        |
| magazine\_id | Integer | Cloned Issue target magazine ID                 |

#### Request Body

| Name       | Type    | Description        |
| ---------- | ------- | ------------------ |
| user\_id   | Integer | Issue User ID      |
| cloneTitle | String  | Cloned Issue title |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Welcome to MagLoft",
  "info": null,
  "hpub": null,
  "source_file": null,
  "source": "typeloft",
  "unlock_type": "free",
  "hide_locked": false,
  "categories": [
    "Sports",
    "Business",
    "Politics"
  ],
  "category_ids": [
    1,
    2,
    3
  ],
  "classifications": [
    "Sports",
    "Business",
    "Politics"
  ],
  "classification_ids": [
    1,
    2,
    3
  ],
  "product_id": "purchase.issue_123456789",
  "product_id_apple": null,
  "product_id_google": null,
  "product_id_amazon": null,
  "screen_type": "issue",
  "publication_id": null,
  "coupon_code": null,
  "dirty": false,
  "user_id": null,
  "custom_stylesheet": null,
  "custom_data": null,
  "price_tier": null,
  "cover": null,
  "generator": "pdfix"
}
```

{% endtab %}
{% endtabs %}

## Sort Issue Articles

<mark style="color:green;">`POST`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id/sort`

This endpoint **sorts** a set of `articles` of an `issue` by `ids` and **returns** an `empty response` with status `204`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

#### Request Body

| Name         | Type  | Description |
| ------------ | ----- | ----------- |
| article\_ids | Array |             |

{% tabs %}
{% tab title="200 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}

## Convert Issue

<mark style="color:orange;">`PUT`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id/convert`

This endpoint converts an `issue` from PDF, EPUB or Folio

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Welcome to MagLoft",
  "info": null,
  "hpub": null,
  "source_file": null,
  "source": "typeloft",
  "unlock_type": "free",
  "hide_locked": false,
  "categories": [
    "Sports",
    "Business",
    "Politics"
  ],
  "category_ids": [
    1,
    2,
    3
  ],
  "classifications": [
    "Sports",
    "Business",
    "Politics"
  ],
  "classification_ids": [
    1,
    2,
    3
  ],
  "product_id": "purchase.issue_123456789",
  "product_id_apple": null,
  "product_id_google": null,
  "product_id_amazon": null,
  "screen_type": "issue",
  "publication_id": null,
  "coupon_code": null,
  "dirty": false,
  "user_id": null,
  "custom_stylesheet": null,
  "custom_data": null,
  "price_tier": null,
  "cover": null,
  "generator": "pdfix"
}
```

{% endtab %}
{% endtabs %}

## Pack an issue to HPUB

<mark style="color:orange;">`PUT`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id/pack`

This endpoint pack an `issue` to HPUB and **returns** the `issue`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Welcome to MagLoft",
  "info": null,
  "hpub": null,
  "source_file": null,
  "source": "typeloft",
  "unlock_type": "free",
  "hide_locked": false,
  "categories": [
    "Sports",
    "Business",
    "Politics"
  ],
  "category_ids": [
    1,
    2,
    3
  ],
  "classifications": [
    "Sports",
    "Business",
    "Politics"
  ],
  "classification_ids": [
    1,
    2,
    3
  ],
  "product_id": "purchase.issue_123456789",
  "product_id_apple": null,
  "product_id_google": null,
  "product_id_amazon": null,
  "screen_type": "issue",
  "publication_id": null,
  "coupon_code": null,
  "dirty": false,
  "user_id": null,
  "custom_stylesheet": null,
  "custom_data": null,
  "price_tier": null,
  "cover": null,
  "generator": "pdfix"
}
```

{% endtab %}
{% endtabs %}

## Export issue to PDF

<mark style="color:orange;">`PUT`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id/export_pdf`

This endpoint converts a TypeLoft 2 `issue` to PDF and **returns** the `issue`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Welcome to MagLoft",
  "info": null,
  "hpub": null,
  "source_file": null,
  "source": "typeloft",
  "unlock_type": "free",
  "hide_locked": false,
  "categories": [
    "Sports",
    "Business",
    "Politics"
  ],
  "category_ids": [
    1,
    2,
    3
  ],
  "classifications": [
    "Sports",
    "Business",
    "Politics"
  ],
  "classification_ids": [
    1,
    2,
    3
  ],
  "product_id": "purchase.issue_123456789",
  "product_id_apple": null,
  "product_id_google": null,
  "product_id_amazon": null,
  "screen_type": "issue",
  "publication_id": null,
  "coupon_code": null,
  "dirty": false,
  "user_id": null,
  "custom_stylesheet": null,
  "custom_data": null,
  "price_tier": null,
  "cover": null,
  "generator": "pdfix"
}
```

{% endtab %}
{% endtabs %}

## Generate Web URL

<mark style="color:orange;">`PUT`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id/generate_web_url`

This endpoint generates a hosted version of an `issue`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "title": "Welcome to MagLoft",
  "info": null,
  "hpub": null,
  "source_file": null,
  "source": "typeloft",
  "unlock_type": "free",
  "hide_locked": false,
  "categories": [
    "Sports",
    "Business",
    "Politics"
  ],
  "category_ids": [
    1,
    2,
    3
  ],
  "classifications": [
    "Sports",
    "Business",
    "Politics"
  ],
  "classification_ids": [
    1,
    2,
    3
  ],
  "product_id": "purchase.issue_123456789",
  "product_id_apple": null,
  "product_id_google": null,
  "product_id_amazon": null,
  "screen_type": "issue",
  "publication_id": null,
  "coupon_code": null,
  "dirty": false,
  "user_id": null,
  "custom_stylesheet": null,
  "custom_data": null,
  "price_tier": null,
  "cover": null,
  "generator": "pdfix"
}
```

{% endtab %}
{% endtabs %}

## Process Filename

<mark style="color:orange;">`PUT`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id/process_links`

This endpoint process an `issue` filename links in TypeLoft Pages and **returns** an `empty response` with status `204`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

{% tabs %}
{% tab title="200 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}

## Delete Issue

<mark style="color:red;">`DELETE`</mark> `https://www.magloft.com/api/portal/v1/issues/:app_id/:id`

This endpoint **deletes** a specific `issue` by `id` and **returns** an `empty response` with status `204`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Issue ID                                        |

{% tabs %}
{% tab title="200 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}