> For the complete documentation index, see [llms.txt](https://api.docs.magloft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.docs.magloft.com/portal-api/issues.md).

# 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.docs.magloft.com/portal-api/issues.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.