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. You can also create (and delete) draft issues so you can prepare a new issue with 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

Fetching all data for a specific issue

Creating a draft issue

Deleting a draft issue

Fetching the list of issues

This API is located at:

GET /publications/{publication_id}/issues

There are 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.
  • state - Can be set to published to return only published issues or draft to return only draft issues.
  • stats - If set to true results will include open and click rates for issues.

Example

To test this API, you can use cURL:

curl -X GET https://api.curated.co/api/v3/publications/PUBLICATION_ID/issues \
-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 results which are available.
  • data - 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

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

Fetching all data for a specific issue

This API is located at:

GET /publications/{publication_id}/issues/{issue_number}

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

  • issue_number - Required. Which issue number should be fetched, this number should correspond to the number fetched from the call to the issues API above, but it will also accept id. If the issue is not published, it will only accept the id.

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

  • issue_number - Required. Which issue number should be fetched, this number should correspond to the number fetched from the call to the issues API above, but it will also accept id. If the issue is not published, it will only accept the id.
  • stats - Optional. If set to true, result will show the open and click rate as well as the click counts for links inside of a published issue.

Example

To test this API, you can use cURL:

curl -X GET https://api.curated.co/api/v3/publications/PUBLICATION_ID/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:

  • id - The database ID of the issue (used when managing draft issues).
  • 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": []
        }
      ]
    }
  ]
}

Creating a draft issue

A call to this endpoint will create a draft issue with your default publication settings.

This API is located at:

POST /publications/{publication_id}/issues/

Deleting a draft issue

Only draft issues may be deleted.

This API is located at:

DELETE /publications/{publication_id}/issues/{id}

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

  • id - Required. Must be the id of the draft issue, obtained from retrieving the list of issues.