Juga.io API 1.1

This API Blueprint documents Juga.io's public REST API.

If you are bootstrapping a project also take a look at Demo Project sources. It is a medium size nodejs example with many features and integrations (Feed reading, Categories, One Signal, Facebook Instant Articles RSS, etc.).

Feed

A feed is a publishing channel.

Using juga.io, editors can create items and then schedule them for publishing into feeds.

Developers can read the feeds using this API and automatically embed the items inside websites, Facebook Instant Articles or App webviews. They can also automatically publish notifications on social networks. etc.

The common usage is to create one feed for each website you manage and then populate your website with the content of the feed.

If your website has a lot of traffic you may prefer to create one feed per section or language.

Read feed description

Read feed description
GET/feed/{feed_id}

Returns a feed meta data.

URI Parameters
HideShow
feed_id
uuid (required) Example: UUID-Feed-Entry-ID

Unique feed identifier.

GET https://api.juga.io/api/1.1/feed/UUID-Feed-Entry-ID
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "UUID-Feed-ID",
  "lang": "en",
  "name": "Some feed",
  "description": "This feed is a great feed",
  "facebookPageId": "fb-page-id",
  "facebookPageName": "fb-page-name"
}
Response Attributes
idstring(optional)

    id of the feed

    langstring(optional)

      lang code of the feed

      namestring(optional)

        The name of the feed

        descriptionstring(optional)

          Description of the feed

          facebookPageIdstring(optional)

            The facebook page ID for this feed

            facebookPageNamestring(optional)

              The facebook page name for this feed

              Response Schema
              HideShow
              {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "id of the feed"
                  },
                  "lang": {
                    "type": "string",
                    "description": "lang code of the feed"
                  },
                  "name": {
                    "type": "string",
                    "description": "The name of the feed"
                  },
                  "description": {
                    "type": "string",
                    "description": "Description of the feed"
                  },
                  "facebookPageId": {
                    "type": "string",
                    "description": "The facebook page ID for this feed"
                  },
                  "facebookPageName": {
                    "type": "string",
                    "description": "The facebook page name for this feed"
                  }
                }
              }

              Read feed content

              Read feed content
              GET/feed/{feed_id}/entries?page={page}&limit={limit}&future={future}

              Returns a specific feed content.

              Use this route to get the latest scheduled items.

              URI Parameters
              HideShow
              feed_id
              uuid (required) Example: UUID-Feed-ID

              Unique feed identifier.

              page
              int (optional) Default: 0 Example: 2

              Browsing page number.

              limit
              int (optional) Default: 100 Example: 100

              Browsing entries per page.

              future
              boolean (optional) Default: false Example: false

              Include future entries

              GET https://api.juga.io/api/1.1/feed/UUID-Feed-ID/entries?page=2&limit=100&future=false
              Responses200
              Headers
              Content-Type: application/json
              Body
              [
                {
                  "id": "UUID-Feed-Entry-ID",
                  "feedId": "UUID-Feed-ID",
                  "itemId": "UUID-Item-ID",
                  "date": 1517332163258,
                  "kind": "Quiz",
                  "title": "My item's title",
                  "image": "http://example.com/item.jpg",
                  "description": {
                    "text": "# My markdown source",
                    "html": "<h1>My markdown source</h1>"
                  }
                }
              ]
              Response Attributes
              Array of:
              idenum(required)
              • Choices: 
                • UUID-Feed-Entry-ID

              id of the FeedEntry, unique identifier of item occurence inside a feed

              feedIdenum(required)
              • Choices: 
                • UUID-Feed-ID

              feed id

              itemIdenum(required)
              • Choices: 
                • UUID-Item-ID

              item id

              dateenum(required)
              • Choices: 
                • 1517332163258

              publish date (ms since the epoch)

              kindenum(required)
              • Choices: 
                • Article
                • Quiz
                • Test
                • Calculator
                • Slideshow
                • HotOrNot
                • OpenQuiz
                • VersusWar
                • Tournament
                • Quiz

              kind of the item

              titleenum(required)
              • Choices: 
                • My item's title

              title of the item

              imageenum(optional)
              • Choices: 
                • http://example.com/item.jpg

              meta image of the item

              descriptionobject(required)

                description of the item

                textenum(required)
                • Choices: 
                  • # My markdown source

                Markdown source text

                htmlenum(required)
                • Choices: 
                  • <h1>My markdown source</h1>

                Resulting HTML

                customenum(optional)
                • Choices: 

                a custom field you can use to pass meta data along juga.io's items

                Response Schema
                HideShow
                {
                  "$schema": "http://json-schema.org/draft-04/schema#",
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "enum": [
                          "UUID-Feed-Entry-ID"
                        ],
                        "description": "id of the FeedEntry, unique identifier of item occurence inside a feed"
                      },
                      "feedId": {
                        "type": "string",
                        "enum": [
                          "UUID-Feed-ID"
                        ],
                        "description": "feed id"
                      },
                      "itemId": {
                        "type": "string",
                        "enum": [
                          "UUID-Item-ID"
                        ],
                        "description": "item id"
                      },
                      "date": {
                        "type": "number",
                        "enum": [
                          1517332163258
                        ],
                        "description": "publish date (ms since the epoch)"
                      },
                      "kind": {
                        "type": "string",
                        "enum": [
                          "Article",
                          "Quiz",
                          "Test",
                          "Calculator",
                          "Slideshow",
                          "HotOrNot",
                          "OpenQuiz",
                          "VersusWar",
                          "Tournament",
                          "Quiz"
                        ],
                        "description": "kind of the item"
                      },
                      "title": {
                        "type": "string",
                        "enum": [
                          "My item's title"
                        ],
                        "description": "title of the item"
                      },
                      "image": {
                        "type": "string",
                        "enum": [
                          "http://example.com/item.jpg"
                        ],
                        "description": "meta image of the item"
                      },
                      "description": {
                        "type": "object",
                        "properties": {
                          "text": {
                            "type": "string",
                            "enum": [
                              "# My markdown source"
                            ],
                            "description": "Markdown source text"
                          },
                          "html": {
                            "type": "string",
                            "enum": [
                              "<h1>My markdown source</h1>"
                            ],
                            "description": "Resulting HTML"
                          }
                        },
                        "required": [
                          "text",
                          "html"
                        ],
                        "additionalProperties": false,
                        "description": "description of the item"
                      },
                      "custom": {
                        "type": "string",
                        "enum": [
                          ""
                        ],
                        "description": "a custom field you can use to pass meta data along juga.io's items"
                      }
                    },
                    "required": [
                      "id",
                      "feedId",
                      "itemId",
                      "date",
                      "kind",
                      "title",
                      "description"
                    ],
                    "additionalProperties": false
                  }
                }

                Read one feed entry

                Read one feed entry
                GET/feed/{feed_id}/entry/{entry_id}

                URI Parameters
                HideShow
                feed_id
                uuid (required) Example: UUID-Feed-ID

                Unique feed identifier.

                entry_id
                uuid (required) Example: UUID-Feed-Entry-ID

                Unique feed entry identifier.

                GET https://api.juga.io/api/1.1/feed/UUID-Feed-ID/entry/UUID-Feed-Entry-ID
                Responses200
                Headers
                Content-Type: application/json
                Body
                {
                  "id": "UUID-Feed-Entry-ID",
                  "feedId": "UUID-Feed-ID",
                  "itemId": "UUID-Item-ID",
                  "date": 1517332163258,
                  "kind": "Quiz",
                  "title": "My item's title",
                  "image": "http://example.com/item.jpg",
                  "description": {
                    "text": "# My markdown source",
                    "html": "<h1>My markdown source</h1>"
                  }
                }
                Response Attributes
                idstring(optional)

                  id of the FeedEntry, unique identifier of item occurence inside a feed

                  feedIdstring(optional)

                    feed id

                    itemIdstring(optional)

                      item id

                      datenumber(optional)

                        publish date (ms since the epoch)

                        kindenum(optional)
                        • Choices: 
                          • Article
                          • Quiz
                          • Test
                          • Calculator
                          • Slideshow
                          • HotOrNot
                          • OpenQuiz
                          • VersusWar
                          • Tournament
                          • Quiz

                        kind of the item

                        titlestring(optional)

                          title of the item

                          imagestring(optional)

                            meta image of the item

                            descriptionobject(optional)

                              description of the item

                              textstring(optional)

                                Markdown source text

                                htmlstring(optional)

                                  Resulting HTML

                                  customstring(optional)

                                    a custom field you can use to pass meta data along juga.io's items

                                    Response Schema
                                    HideShow
                                    {
                                      "$schema": "http://json-schema.org/draft-04/schema#",
                                      "type": "object",
                                      "properties": {
                                        "id": {
                                          "type": "string",
                                          "description": "id of the FeedEntry, unique identifier of item occurence inside a feed"
                                        },
                                        "feedId": {
                                          "type": "string",
                                          "description": "feed id"
                                        },
                                        "itemId": {
                                          "type": "string",
                                          "description": "item id"
                                        },
                                        "date": {
                                          "type": "number",
                                          "description": "publish date (ms since the epoch)"
                                        },
                                        "kind": {
                                          "type": "string",
                                          "enum": [
                                            "Article",
                                            "Quiz",
                                            "Test",
                                            "Calculator",
                                            "Slideshow",
                                            "HotOrNot",
                                            "OpenQuiz",
                                            "VersusWar",
                                            "Tournament",
                                            "Quiz"
                                          ],
                                          "description": "kind of the item"
                                        },
                                        "title": {
                                          "type": "string",
                                          "description": "title of the item"
                                        },
                                        "image": {
                                          "type": "string",
                                          "description": "meta image of the item"
                                        },
                                        "description": {
                                          "type": "object",
                                          "properties": {
                                            "text": {
                                              "type": "string",
                                              "description": "Markdown source text"
                                            },
                                            "html": {
                                              "type": "string",
                                              "description": "Resulting HTML"
                                            }
                                          },
                                          "description": "description of the item"
                                        },
                                        "custom": {
                                          "type": "string",
                                          "description": "a custom field you can use to pass meta data along juga.io's items"
                                        }
                                      }
                                    }

                                    Item

                                    Data

                                    Data
                                    GET/item/{item_id}

                                    URI Parameters
                                    HideShow
                                    item_id
                                    uuid (required) Example: UUID-Item-ID

                                    Unique item identifier.

                                    GET https://api.juga.io/api/1.1/item/UUID-Item-ID
                                    Responses200
                                    Headers
                                    Content-Type: application/json
                                    Body
                                    {
                                      "id": "UUID-Item-ID",
                                      "lang": "en",
                                      "date": 1517332163258,
                                      "kind": "Quiz",
                                      "accountId": "UUID-Account-ID",
                                      "title": "My item's title",
                                      "image": "http://example.com/item.jpg",
                                      "description": {
                                        "text": "# My markdown source",
                                        "html": "<h1>My markdown source</h1>"
                                      },
                                      "data": ""
                                    }
                                    Response Attributes
                                    idstring(optional)

                                      The item unique id

                                      langstring(optional)

                                        The lang code for this item

                                        datenumber(optional)

                                          Item last update date

                                          kindenum(optional)
                                          • Choices: 
                                            • Article
                                            • Quiz
                                            • Test
                                            • Calculator
                                            • Slideshow
                                            • HotOrNot
                                            • OpenQuiz
                                            • VersusWar
                                            • Tournament
                                            • Quiz

                                          kind of the item

                                          accountIdstring(optional)

                                            Owner account unique id

                                            titlestring(optional)

                                              title of the item

                                              imagestring(optional)

                                                meta image of the item

                                                descriptionobject(optional)

                                                  description of the item

                                                  textstring(optional)

                                                    Markdown source text

                                                    htmlstring(optional)

                                                      Resulting HTML

                                                      datastring(optional)

                                                        item data, usually a json stringified

                                                        customstring(optional)

                                                          a custom field you can use to pass meta data along juga.io's items

                                                          Response Schema
                                                          HideShow
                                                          {
                                                            "$schema": "http://json-schema.org/draft-04/schema#",
                                                            "type": "object",
                                                            "properties": {
                                                              "id": {
                                                                "type": "string",
                                                                "description": "The item unique id"
                                                              },
                                                              "lang": {
                                                                "type": "string",
                                                                "description": "The lang code for this item"
                                                              },
                                                              "date": {
                                                                "type": "number",
                                                                "description": "Item last update date"
                                                              },
                                                              "kind": {
                                                                "type": "string",
                                                                "enum": [
                                                                  "Article",
                                                                  "Quiz",
                                                                  "Test",
                                                                  "Calculator",
                                                                  "Slideshow",
                                                                  "HotOrNot",
                                                                  "OpenQuiz",
                                                                  "VersusWar",
                                                                  "Tournament",
                                                                  "Quiz"
                                                                ],
                                                                "description": "kind of the item"
                                                              },
                                                              "accountId": {
                                                                "type": "string",
                                                                "description": "Owner account unique id"
                                                              },
                                                              "title": {
                                                                "type": "string",
                                                                "description": "title of the item"
                                                              },
                                                              "image": {
                                                                "type": "string",
                                                                "description": "meta image of the item"
                                                              },
                                                              "description": {
                                                                "type": "object",
                                                                "properties": {
                                                                  "text": {
                                                                    "type": "string",
                                                                    "description": "Markdown source text"
                                                                  },
                                                                  "html": {
                                                                    "type": "string",
                                                                    "description": "Resulting HTML"
                                                                  }
                                                                },
                                                                "description": "description of the item"
                                                              },
                                                              "data": {
                                                                "type": "string",
                                                                "description": "item data, usually a json stringified"
                                                              },
                                                              "custom": {
                                                                "type": "string",
                                                                "description": "a custom field you can use to pass meta data along juga.io's items"
                                                              }
                                                            }
                                                          }

                                                          Scores

                                                          Scores
                                                          GET/item/{item_id}/score

                                                          Score API is used by Quiz and OpenQuiz contents.

                                                          For scalability reason juga.io is not offering a full ranking API but an approximative one using a segmented statistic table.

                                                          URI Parameters
                                                          HideShow
                                                          item_id
                                                          uuid (required) Example: UUID-Item-ID

                                                          Unique item identifier.

                                                          GET https://api.juga.io/api/1.1/item/UUID-Item-ID/score
                                                          Responses200
                                                          Headers
                                                          Content-Type: application/json
                                                          Body
                                                          {
                                                            "id": "UUID-Item-ID",
                                                            "maxScore": 100,
                                                            "plays": 999,
                                                            "cumulatedScore": 10400,
                                                            "segments": {
                                                              "<segment_id>": 0
                                                            }
                                                          }
                                                          Response Attributes
                                                          idstring(optional)

                                                            Item id

                                                            maxScorenumber(optional)

                                                              Maximum score expected for this item

                                                              playsnumber(optional)

                                                                Number of plays (i.e.: number of saved scores)

                                                                cumulatedScorenumber(optional)

                                                                  Sum of all saved scores

                                                                  segmentsobject(optional)

                                                                    Keys are the score segment index as string, values are the number of registered scores falling in the segment.

                                                                    <segment_id>number(optional)

                                                                      Keys are the score segment index as string, values are the number of registered scores falling in the segment.

                                                                      Response Schema
                                                                      HideShow
                                                                      {
                                                                        "$schema": "http://json-schema.org/draft-04/schema#",
                                                                        "type": "object",
                                                                        "properties": {
                                                                          "id": {
                                                                            "type": "string",
                                                                            "description": "Item id"
                                                                          },
                                                                          "maxScore": {
                                                                            "type": "number",
                                                                            "description": "Maximum score expected for this item"
                                                                          },
                                                                          "plays": {
                                                                            "type": "number",
                                                                            "description": "Number of plays (i.e.: number of saved scores)"
                                                                          },
                                                                          "cumulatedScore": {
                                                                            "type": "number",
                                                                            "description": "Sum of all saved scores"
                                                                          },
                                                                          "segments": {
                                                                            "type": "object",
                                                                            "properties": {
                                                                              "<segment_id>": {
                                                                                "type": "number",
                                                                                "description": "Keys are the score segment index as string, values are the number of registered scores falling in the segment."
                                                                              }
                                                                            },
                                                                            "description": "Keys are the score segment index as string, values are the number of registered scores falling in the segment."
                                                                          }
                                                                        }
                                                                      }

                                                                      Vote

                                                                      Vote
                                                                      GET/item/{item_id}/vote/export

                                                                      Some juga.io items support a vote kind of interaction (i.e.: Slideshow, HotOrNot, etc.).

                                                                      You can programmatically access the results of user interaction using the following endpoints.

                                                                      Returns a readable export of vote statistics.

                                                                      Use this route to develop widgets and representations of users’ votes.

                                                                      Ranking and scores are computed accordingly to the rules of the vote.

                                                                      URI Parameters
                                                                      HideShow
                                                                      item_id
                                                                      uuid (required) Example: UUID-Item-ID

                                                                      Unique item identifier.

                                                                      GET https://api.juga.io/api/1.1/item/UUID-Item-ID/vote/export
                                                                      Responses200
                                                                      Headers
                                                                      Content-Type: application/json
                                                                      Body
                                                                      {
                                                                        "id": "UUID-Item-ID",
                                                                        "isOpen": true,
                                                                        "rules": "note",
                                                                        "results": [
                                                                          {
                                                                            "id": 5,
                                                                            "pos": 0,
                                                                            "title": "Luke Skywalker",
                                                                            "image": "http://example.com/img.png",
                                                                            "note": 0.4,
                                                                            "score": 10,
                                                                            "votes": 88,
                                                                            "downs": 12
                                                                          }
                                                                        ]
                                                                      }
                                                                      Response Attributes
                                                                      idstring(optional)

                                                                        Item’s unique id.

                                                                        isOpenboolean(optional)

                                                                          Vote is open to users

                                                                          rulesenum(optional)
                                                                          • Choices: 
                                                                            • all
                                                                            • one
                                                                            • updown
                                                                            • note
                                                                            • note

                                                                          Voting rules

                                                                          resultsarray(optional)

                                                                            Exported results

                                                                            Response Schema
                                                                            HideShow
                                                                            {
                                                                              "$schema": "http://json-schema.org/draft-04/schema#",
                                                                              "type": "object",
                                                                              "properties": {
                                                                                "id": {
                                                                                  "type": "string",
                                                                                  "description": "Item's unique id."
                                                                                },
                                                                                "isOpen": {
                                                                                  "type": "boolean",
                                                                                  "description": "Vote is open to users"
                                                                                },
                                                                                "rules": {
                                                                                  "type": "string",
                                                                                  "enum": [
                                                                                    "all",
                                                                                    "one",
                                                                                    "updown",
                                                                                    "note",
                                                                                    "note"
                                                                                  ],
                                                                                  "description": "Voting rules"
                                                                                },
                                                                                "results": {
                                                                                  "type": "array",
                                                                                  "description": "Exported results"
                                                                                }
                                                                              }
                                                                            }

                                                                            Versus

                                                                            Versus
                                                                            GET/item/{item_id}/versus

                                                                            Versus API is used inside VersusWar and Tournament contents.

                                                                            URI Parameters
                                                                            HideShow
                                                                            item_id
                                                                            uuid (required) Example: UUID-Item-ID

                                                                            Unique item identifier.

                                                                            GET https://api.juga.io/api/1.1/item/UUID-Item-ID/versus
                                                                            Responses200
                                                                            Headers
                                                                            Content-Type: application/json
                                                                            Body
                                                                            {
                                                                              "id": "UUID-Item-ID",
                                                                              "isOpen": true,
                                                                              "stats": {
                                                                                "<candidateId>": {
                                                                                  "id": 0,
                                                                                  "fights": 10,
                                                                                  "wins": 8
                                                                                }
                                                                              }
                                                                            }
                                                                            Response Attributes
                                                                            idstring(optional)

                                                                              Item id

                                                                              isOpenboolean(optional)

                                                                                Versus is open to users

                                                                                statsobject(optional)

                                                                                  Versus statistics

                                                                                  <candidateId>object(optional)
                                                                                    idnumber(optional)

                                                                                      Candidate id

                                                                                      fightsnumber(optional)

                                                                                        Number of fights

                                                                                        winsnumber(optional)

                                                                                          Number of victories

                                                                                          Response Schema
                                                                                          HideShow
                                                                                          {
                                                                                            "$schema": "http://json-schema.org/draft-04/schema#",
                                                                                            "type": "object",
                                                                                            "properties": {
                                                                                              "id": {
                                                                                                "type": "string",
                                                                                                "description": "Item id"
                                                                                              },
                                                                                              "isOpen": {
                                                                                                "type": "boolean",
                                                                                                "description": "Versus is open to users"
                                                                                              },
                                                                                              "stats": {
                                                                                                "type": "object",
                                                                                                "properties": {
                                                                                                  "<candidateId>": {
                                                                                                    "type": "object",
                                                                                                    "properties": {
                                                                                                      "id": {
                                                                                                        "type": "number",
                                                                                                        "description": "Candidate id"
                                                                                                      },
                                                                                                      "fights": {
                                                                                                        "type": "number",
                                                                                                        "description": "Number of fights"
                                                                                                      },
                                                                                                      "wins": {
                                                                                                        "type": "number",
                                                                                                        "description": "Number of victories"
                                                                                                      }
                                                                                                    }
                                                                                                  }
                                                                                                },
                                                                                                "description": "Versus statistics"
                                                                                              }
                                                                                            }
                                                                                          }

                                                                                          Embedding

                                                                                          This section describes how you can display juga.io items inside your properties and how to customize them.

                                                                                          HTML embed

                                                                                          Our content can be embed right inside your HTML and customized using CSS.

                                                                                          To embed a juga.io item in your webpage you will need to:

                                                                                          1. Include some CSS in your <head>:
                                                                                          <link
                                                                                            rel="stylesheet" style="text/css"
                                                                                            href="https://cdn.juga.io/css/jugaio.css" />
                                                                                          1. Include your different items in your HTML.

                                                                                          Important: the ItemID-UUID must be replace by the ID of the item you want to embed. You will usually take it from the itemId field of feed entries.

                                                                                          <div class="juga-io" data-juga-io-item="ItemID-UUID"></div>
                                                                                          1. Include our javascript
                                                                                          <script src="https://cdn.juga.io/jugaio-client-deps.js"
                                                                                                  type="text/javascript"></script>
                                                                                          <script src="https://cdn.juga.io/jugaio.js"
                                                                                                  type="text/javascript"></script>