Submitting Content

Object representing your content submission to the database.

You need both your source and your API key to identify and submit your content. The first time you submit it, the source is created in real-time. You should keep each source submission limited to 2000 entries.

If you add two contents with the same ID to your source, the most recent item takes precedence, overwriting the previous entry.

Endpoint - POST /$source

Header Value Description
Content-Type “application/json” String indicating that the submitting body format is JSON.
x-api-key Your API key String representing the value of the API key we sent you when you joined Rumo.


Example request (with non-weighted categories):

curl -X POST \
  https://beta.api.rumo.co/{{$source}} \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: Your_Rumo_API_Key' \
  -d '[
        {
            "id" : "1",
            "label" : "Toy Story (1995)",
            "categories" : {
                "genres" : ["Adventure", "Animation", "Children", "Comedy", "Fantasy"],
                "directors" : ["John Lasseter"]
            }        
        },
        {
            "id" : "2",
            "label" : "Twelve Monkeys (1995)",
            "categories" : {
                "genres" : ["Mystery", "Sci-Fi", "Thriller"],
                "directors" : ["Terry Gilliam"]
            }        
        },
        {
            "id" : "3",
            "label" : "10 Things I Hate About You (1999)",
            "categories" : {
                "genres" : ["Comedy", "Romance"],
                "directors" : ["Gil Junger"]
            }        
        }
    ]'


Example request (with weighted categories and filters):

curl -X POST \
  https://beta.api.rumo.co/{{$source}} \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: Your_Rumo_API_Key' \
  -d '[
        {
            "id": "123",
            "label": "Star Wars : Episode V – The Empire Strikes Back",
            "categories": {
                "Mood" : [
                    {"key" : "spectacular" , "weight" : 85},
                    {"key" : "new horizons" , "weight" : 60},
                    {"key" : "family" , "weight" : 55},
                    {"key" : "suspense" , "weight" : 55}
                ],
                "Theme" : [
                    {"key" : "space operas" , "weight" : 100},
                    {"key" : "special effects" , "weight" : 93},
                    {"key" : "superpowers" , "weight" : 78},
                    {"key" : "famous soundtracks" , "weight" : 65},
                    {"key" : "meditation" , "weight" : 40},
                    {"key" : "resistance and collaborators" , "weight" : 18}
                ],
                "Character" : [
                    {"key" : "robots" , "weight" : 78},
                    {"key" : "aliens" , "weight" : 78},
                    {"key" : "wise sages" , "weight" : 40}
                ],
                "Format" : [
                    {"key" : "fiction films"}
                ],
                "Target audience" : [
                    {"key" : "g-rated movies"}
                    ]
                },
            "filters" : {
                    "catalogs" : ["tv"]
                }
        }
    ]'


JSON response

{
    "correlationId": "91077d22-14c9-4907-b207-ceee742fd7b8"
}


Attribute Level Status Description
id 1 Mandatory String used to identify a content piece.
label 1 Optional String used to label a content piece, representing, for example, a movie headline, a song title, or whatever the nature of the content.
categories 1 Mandatory Field value object, where fields can be anything and are used to classify each content piece. The field value can be either a string map (non-weighted categories) or an object map (weighted categories).
filters 1 Optional String used to establish limits to the pool of content. The effectiveness of your filters depends on the quality of the keywords you use within your content.

Your access to filters depends on your subscription plan.
key 3 Optional String used to organize and categorize your content.
Filters use the keywords specified in your content database.

Keyword definition is important and improves the precision of the content recommendations. You should be accurate and refined when specifying your keywords.
weight 3 Optional Integer identifying the weight of a keyword. Weights are used to establish a hierarchy for the keywords.

Weight attribution improves the precision of the content recommendations.

When assigning weights, bear in mind that each keyword has one defined weight for every single entry of the content database. Our API will only process instances of weighted-keywords with assigned values.

Rumo supports as many categories (level-2 or below) as you may need. For example, within categories, you can define genres such as “Adventure, “Animation, or “Comedy,” and directors such as “John Lasseter.”


Returns Description
correlationID String identifying a successful content submission. It can assume different values.

In the future, you will be able to use it to check the status of your content uploads.
code exceptions HTTP status code identifying that the source submission to the database was unsuccessful.

We’re still working on code exceptions. Please bear with us if you notice inconsistencies during the beta stage.