Fetching Issue Data with the API

If you would like to present the data published with Curated in a different way or include something like a summary of issues on another site, all published issue data is available via the API.

In order to interact with this API you will need to read Getting started with the Curated API.

Fetching the list of issues

This API is located at:

GET /issues

There are two optional parameters which can be supplied. These should be passed on the query string:

  • per_page - How many issues to include in the results. The default value for this is 10 and the maximum value is 250.
  • page - Which page of data to retrieve. This will be affected by the per_page parameter above.

To test this API, you can use cURL:

curl -X GET https://api.curated.co/PUBLICATION_KEY/api/v1/issues/ISSUE_NUMBER -H "Accept: application/json" -H "Content-type: application/json" -H 'Authorization: Token token="API_KEY"'

Response Data Format

Returns a dictionary with the following fields:

  • page - The page number for the data returned in this call.
  • total_pages - How many pages are available using this page size.
  • total_results - The total number of issues which are available.
  • issues - An array of Issue Summary dictionaries.

Each Issue Summary dictionary contains the following fields:

  • number - The issue number, this should be used as the parameter when requesting the full set of data for a specific issue (see below).
  • title - The title of the issue.
  • summary - The issue summary.
  • url - The public URL where this issue is available.
  • published_at - The date that the issue was published in ISO 8601 format.
  • updated_at - The date that the issue was last updated (may be after publishing) in ISO 8601 format.

Example Response Data

{
  "page": 1,
  "total_pages": 1,
  "total_results": 1,
  "issues": [
    {
      "number": 1,
      "title": "Issue 1",
      "summary": "This is the issue summary",
      "url": "https://your-publication.curated.co/issues/1",
      "published_at": "2014-08-16T01:21:58.390+01:00",
      "updated_at": "2014-08-24T12:00:03.535+01:00"
    }
  ]
}

Fetching all data for a specific issue

This API is located at:

GET /issues/ISSUE_NUMBER

There is one parameter and it should be passed as part of the URL.

  • issue_number - Which issue number should be fetched, this number should correspond to the number fetched from the call to the issues API above.

To test this API, you can use cURL:

curl -X GET https://api.curated.co/PUBLICATION_KEY/api/v1/issues/ISSUE_NUMBER -H "Accept: application/json" -H "Content-type: application/json" -H 'Authorization: Token token="API_KEY"'

Response Data Format

Returns a dictionary with the following fields:

  • number - The issue number (not usually displayed publicly).
  • title - The title of the issue.
  • summary - The issue summary.
  • url - The public URL where this issue is available.
  • published_at - The date that the issue was published in ISO 8601 format.
  • updated_at - The date that the issue was last updated (may be after publishing) in ISO 8601 format.
  • categories - An array of Category dictionaries. This data will be returned in the order of categories displayed on the public site.

Each Category dictionary contains the following fields:

  • name - The display name of the category.
  • code - The identifier for the category (not usually displayed publicly).
  • items - An array of either Text Item or Link Item dictionaries.

Each Text Item dictionary contains the following fields:

  • type - Either Text or Link, this determines whether this is a Text Item or a Link Item (not usually displayed publicly).
  • title - The title of the item.
  • description - The body text of the item. All Markdown will have been converted to HTML.
  • footer - The footer text of the item. All Markdown will have been converted to HTML.
  • embedded_links - An array of Embedded Link dictionaries.

Each Link Item dictionary contains the following fields:

  • type - Either Text or Link, this determines whether this is a Text Item or a Link Item (not usually displayed publicly).
  • title - The title of the item.
  • description - The body text of the item. All Markdown will have been converted to HTML.
  • url - The short URL for this link.
  • url_domain - The short URL destination’s domain name.
  • embedded_links - An array of Embedded Link dictionaries.

Each Embedded Link dictionary contains the following fields:

  • identifier - The unique identifier for the short link (not usually displayed publicly).
  • title - The title of the short link (not usually displayed publicly).
  • url - The short URL for this embedded link.
  • url_domain - The short URL destination’s domain name.

Example Response Data

{
  "number": 1,
  "title": "Issue 1",
  "summary": "Issue summary",
  "url": "https://your-publication.curated.co/issues/1",
  "published_at": "2014-08-16T01:21:58.390+01:00",
  "updated_at": "2014-08-24T12:00:03.535+01:00",
  "categories": [
    {
      "name": "News",
      "code": "news",
      "items": [
        {
          "type": "Text",
          "title": "Item title",
          "description": "<p>This is the description for a text item in the issue, it will passed as HTML with <strong>formatting</strong> already applied and <a href=\"https://cur.at/5dsYv2s\">embedded links</a> inline.</p>",
          "footer": "Footer text",
          "embedded_links": [
            {
              "identifier": "5dsYv2s",
              "title": "Embedded link title",
              "url": "https://cur.at/5dsYv2s",
              "url_domain": "example.com"
            }
          ]
        },
        {
          "type": "Link",
          "title": "Item title",
          "description": "<p>This is the description for a link item in the issue, it will passed as HTML with <strong>formatting</strong> already applied.</p>",
          "url_domain": "example.com",
          "url": "https://cur.at/8wnuSy6",
          "embedded_links": []
        }
      ]
    }
  ]
}