Back to top

Nuvolar API

Nuvolar

Welcome to the Nuvolar API. This API provides access to the Nuvolar content analysis services.

Domains

A domain is a logical contents repository consisting of different medias like PDFs, Open Format documents, Microsoft Office documents, videos, text files.

List domains

List domains
GET/domains

Get a list of available domains for your account.

Example URI

GET https://backend.nuvolar.it/api/v2/domains
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
        "data": [
            {
                "name": "Domain 1",
                "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
                "logo": "https://backend.nuvolar.it/api/v2/domains/ac6a8620-123e-11e8-924e-1f859a90ac04/logo.png",
                "enabled": false,
                "nuvolarized": true,
                "language": "en_GB",
                "uuid": "ac6a8620-123e-11e8-924e-1f859a90ac04"
            },
            {
                "name": "Domain 2",
                "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
                "logo": "https://backend.nuvolar.it/api/v2/domains/a7925120-123e-11e8-b44e-fdc488b4e238/logo.png",
                "enabled": false,
                "nuvolarized": true,
                "language": "it_IT",
                "uuid": "a7925120-123e-11e8-b44e-fdc488b4e238"
            },
            ...
        ],
        "links": {
            "first": "https://backend.nuvolar.it/api/v2/domains?page=0",
            "last": "https://backend.nuvolar.it/api/v2/domains?page=6",
            "prev": null,
            "next": "https://backend.nuvolar.it/api/v2/domains?page=1"
        },
        "meta": {
            "current_page": 0,
            "from": 0,
            "to": 4,
            "last_page": 6,
            "path": "https://backend.nuvolar.it/api/v2/domains",
            "per_page": 5,
            "total": 31
        }
    }
Response  401
HideShow
Body
Unauthenticated.

Get a domain

Get a domain
GET/domains/{id}

Return an object representing the requested domain.

Example URI

GET https://backend.nuvolar.it/api/v2/domains/7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9
URI Parameters
HideShow
id
string (required) Example: 7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9

Id of the domain to retrieve.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "uuid": "7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9",
    "title": "My domain title",
    "language": "it_IT",
    "logo": "https://yourcompany.com/your_logo.png",
    "description": "My domain's description",
    "enabled": false,
    "contents": {
      "count": 0,
      "storage_allocation": 0
    },
    "quotas": {
      "queries": 0
    }
  }
}
Response  401
HideShow
Body
Unauthenticated.
Response  403
HideShow
Body
Quota exceeded.
Response  404
HideShow
Body
Not found.

Create domains

Create domains
POST/domains

Create a new domain. When creating a domain you must provide a title and a language. Optionally you can also pass through a logo (as a valid image URL), a simple user password for Nuvolar interface interactions, a description and the initial status for the domain (enabled or not).

Example URI

POST https://backend.nuvolar.it/api/v2/domains
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "New domain title",
  "language": "it_IT",
  "logo": "https://yourcompany.com/your_logo.png",
  "description": "My domain's description",
  "enabled": true
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "uuid": "e392da70-0fdf-11e8-bb1f-258d043dfb6d",
    "title": "New domain title",
    "language": "it_IT",
    "logo": "https://yourcompany.com/your_logo.png",
    "description": "My domain's description",
    "enabled": true,
    "contents": {
      "count": 0,
      "storage_allocation": 0
    },
    "quotas": {
      "queries": 0
    }
  }
}
Response  401
HideShow
Body
Unauthenticated.
Response  403
HideShow
Body
Quota exceeded.

Update domains

Update domains
PUT/domains/{id}

Update a domain.

Example URI

PUT https://backend.nuvolar.it/api/v2/domains/7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9
URI Parameters
HideShow
id
string (required) Example: 7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9

Id of the domain to update.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "enabled": false
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "uuid": "7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9",
    "title": "My domain title",
    "language": "it_IT",
    "logo": "https://yourcompany.com/your_logo.png",
    "description": "My domain's description",
    "enabled": false,
    "contents": {
      "count": 0,
      "storage_allocation": 0
    },
    "quotas": {
      "queries": 0
    }
  }
}

Delete domains

Delete domains
DELETE/domains/{id}

Delete a domain.

Example URI

DELETE https://backend.nuvolar.it/api/v2/domains/7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9
URI Parameters
HideShow
id
string (required) Example: 7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9

Id of the domain to delete.

Response  200
Response  401
HideShow
Body
Unauthenticated.
Response  403
HideShow
Body
Access denied.
Response  404
HideShow
Body
Not found.

Contents

A content is a file to be analyzed, indexed and possibly stored into the Nuvolar backend.

Get contents

Get contents
GET/domains/contents

Get a list of contents belonging to the specified domain.

Example URI

GET https://backend.nuvolar.it/api/v2/domains/contents
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
        "data": [
            {
                "mime_type": "video",
                "title": "Content 1",
                "author": "David Finch",
                "creation_date": "2017-11-14 12:00:08",
                "uuid": "ae1654d0-122d-11e8-ac70-b9cafc1ae222"
            },
            {
                "mime_type": "video",
                "title": "Content 2",
                "author": "Joseph Green",
                "creation_date": "2017-12-05 13:00:05",
                "uuid": "a32d7340-122d-11e8-86b1-0fd0c796e4a6"
            },
            {
                "mime_type": "video",
                "title": "Content 3",
                "author": "Mary White",
                "creation_date": "2017-08-07 11:00:02",
                "uuid": "efd82270-122c-11e8-bcaf-bb1d762cf37f"
            },
            ...
        ],
        "links": {
            "first": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents?page=0",
            "last": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents?page=4",
            "prev": null,
            "next": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents?page=1"
        },
        "meta": {
            "current_page": 0,
            "from": 0,
            "to": 4,
            "last_page": 4,
            "path": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents",
            "per_page": 5,
            "total": 23
        }
    }

Get a content

Get a content
GET/domains/contents/

Return an object representing the requested content.

Example URI

GET https://backend.nuvolar.it/api/v2/domains/contents/
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
        "data": {
            "mime_type": "video",
            "title": "My awesome video",
            "author": "Mr. White",
            "creation_date": "2017-11-14 12:00:08",
            "uuid": "ae1654d0-122d-11e8-ac70-b9cafc1ae222",
            "thumbnails": {
                "low": {
                    "url": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222/thumbnail?type=low",
                    "width": 120,
                    "height": 90
                },
                "medium": {
                    "url": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222/thumbnail?type=medium",
                    "width": 320,
                    "height": 180
                },
                "high": {
                    "url": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222/thumbnail?type=high",
                    "width": 480,
                    "height": 360
                }
            },
            "attributes": {
                "abstract": "",
                "length": "00:12:42",
                "custom": [
                    "collection": "family"
                ]
            },
            "categories": [
                "amateur",
                "videos"
            ],
            "tags": [
                "dog",
                "garden",
                "sun",
                "family",
                "summer",
                "funny"
            ]
        }
    }

Create contents

Create contents
POST/domains/contents

Create a new content.

Example URI

POST https://backend.nuvolar.it/api/v2/domains/contents
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "My awesome video",
  "categories": [
    "amateur",
    "videos"
  ],
  "source": "https://www.my.cnd/that_file.mp4"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
        "data": {
            "mime_type": "video",
            "title": "My awesome video",
            "author": "Mr. White",
            "creation_date": "2017-11-14 12:00:08",
            "uuid": "ae1654d0-122d-11e8-ac70-b9cafc1ae222",
            "thumbnails": {
                "low": {
                    "url": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222/thumbnail?type=low",
                    "width": 120,
                    "height": 90
                },
                "medium": {
                    "url": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222/thumbnail?type=medium",
                    "width": 320,
                    "height": 180
                },
                "high": {
                    "url": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222/thumbnail?type=high",
                    "width": 480,
                    "height": 360
                }
            },
            "attributes": {
                "abstract": "",
                "length": "00:12:42",
                "custom": [
                    "collection": "family"
                ]
            },
            "categories": [
                "amateur",
                "videos"
            ],
            "tags": [
                "dog",
                "garden",
                "sun",
                "family",
                "summer",
                "funny"
            ]
        }
    }

Update contents

Update contents
PUT/domains/{domain_id}/contents/{content_id}

Update a content.

Example URI

PUT https://backend.nuvolar.it/api/v2/domains/7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9/contents/7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9
URI Parameters
HideShow
domain_id
string (required) Example: 7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9

Id of the domain to update.

content_id
string (required) Example: 7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9

Id of the content to update.

Request
HideShow
Headers
Content-Type: application/json
Body
{
        "title": "My awesome video, reloaded",
    }
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
        "data": {
            "mime_type": "video",
            "title": "My awesome video",
            "author": "Mr. White",
            "creation_date": "2017-11-14 12:00:08",
            "uuid": "ae1654d0-122d-11e8-ac70-b9cafc1ae222",
            "thumbnails": {
                "low": {
                    "url": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222/thumbnail?type=low",
                    "width": 120,
                    "height": 90
                },
                "medium": {
                    "url": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222/thumbnail?type=medium",
                    "width": 320,
                    "height": 180
                },
                "high": {
                    "url": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222/thumbnail?type=high",
                    "width": 480,
                    "height": 360
                }
            },
            "attributes": {
                "abstract": "",
                "length": "00:12:42",
                "custom": [
                    "collection": "family"
                ]
            },
            "categories": [
                "amateur",
                "videos"
            ],
            "tags": [
                "dog",
                "garden",
                "sun",
                "family",
                "summer",
                "funny"
            ]
        }
    }
Response  401
HideShow
Body
Unauthenticated.
Response  403
HideShow
Body
Access denied.
Response  404
HideShow
Body
Not found.

Delete contents

Delete contents
DELETE/domains/{id}

Delete a content.

Example URI

DELETE https://backend.nuvolar.it/api/v2/domains/7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9
URI Parameters
HideShow
id
string (required) Example: 7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9

Id of the content to delete.

Response  200
Response  401
HideShow
Body
Unauthenticated.
Response  403
HideShow
Body
Access denied.

Search & Discovery

Nuvolar provides several search & discovery services. The most common ones are full text search and tags search.

Full text search

Full text search
POST/search/fulltext/domains/fulltext

Perform a full text search against the specified domain and return matching content results.

Example URI

POST https://backend.nuvolar.it/api/v2/search/fulltext/domains/fulltext
URI Parameters
HideShow
id
string (required) Example: 7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9

Id of the domain.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "query": "my search"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
        "data": [
            {
                "mime_type": "video",
                "title": "Content 1",
                "author": "David Finch",
                "creation_date": "2017-11-14 12:00:08",
                "uuid": "ae1654d0-122d-11e8-ac70-b9cafc1ae222",
                "url": https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222"
            },
            {
                "mime_type": "video",
                "title": "Content 2",
                "author": "Joseph Green",
                "creation_date": "2017-12-05 13:00:05",
                "uuid": "a32d7340-122d-11e8-86b1-0fd0c796e4a6",
                "url": https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/a32d7340-122d-11e8-86b1-0fd0c796e4a6"
            },
            {
                "mime_type": "video",
                "title": "Content 3",
                "author": "Mary White",
                "creation_date": "2017-08-07 11:00:02",
                "uuid": "efd82270-122c-11e8-bcaf-bb1d762cf37f",
                "url": https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/efd82270-122c-11e8-bcaf-bb1d762cf37f"
            },
            ...
        ],
        "links": {
            "first": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents?page=0",
            "last": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents?page=4",
            "prev": null,
            "next": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents?page=1"
        },
        "meta": {
            "current_page": 0,
            "from": 0,
            "to": 4,
            "last_page": 4,
            "path": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents",
            "per_page": 5,
            "total": 23
        }
    }
Response  401
HideShow
Body
Unauthenticated.
Response  403
HideShow
Body
Access denied.
Response  404
HideShow
Body
Not found.

Terms

Get terms

Get terms
GET/domains/terms

Get a list of terms belonging to the domain with their rank score.

Example URI

GET https://backend.nuvolar.it/api/v2/domains/terms
URI Parameters
HideShow
id
string (required) Example: 7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9

Id of the domain.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
        "data": [
                    {
                        "term": "dog",
                        "rank": "98.85",
                    },
                    {
                        "term": "cat",
                        "rank": "56.73",
                    },
                    {
                        "term": "garden",
                        "rank": "12.44",
                    },
                ]
    }
Response  401
HideShow
Body
Unauthenticated.
Response  403
HideShow
Body
Access denied.
Response  404
HideShow
Body
Not found.

Get rank

Get rank
GET/domains/terms/{term}/rank

Return the rank score for a given term.

Example URI

GET https://backend.nuvolar.it/api/v2/domains/terms/dog/rank
URI Parameters
HideShow
id
string (required) Example: 7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9

Id of the domain.

term
string (required) Example: dog

Term to query.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "rank": 98.85
}
Response  401
HideShow
Body
Unauthenticated.
Response  403
HideShow
Body
Access denied.
Response  404
HideShow
Body
Not found.

Correlations

Terms correlations

Terms correlations
GET/domains/correlations/

Get a list of terms contained in specified domain correlated to the term provided.

Example URI

GET https://backend.nuvolar.it/api/v2/domains/correlations/
URI Parameters
HideShow
id
string (required) Example: dog

Term.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
        "data": [
                    {
                        "term": "dog",
                        "correlation": "98.85",
                    },
                    {
                        "term": "cat",
                        "correlation": "56.73",
                    },
                    {
                        "term": "garden",
                        "correlation": "12.44",
                    },
                ]
    }
Response  401
HideShow
Body
Unauthenticated.
Response  403
HideShow
Body
Access denied.
Response  404
HideShow
Body
Not found.

Documents correlation

Documents correlation
GET/domains/correlations/{term}/contents

Get a list of contents correlated with the given term.

Example URI

GET https://backend.nuvolar.it/api/v2/domains/correlations/dog/contents
URI Parameters
HideShow
id
string (required) Example: 7b96bbf0-11a5-11e8-909d-a1f6c92fc1c9

Id of the domain.

term
string (required) Example: dog

Term to query.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
        "data": [
            {
                "mime_type": "video",
                "title": "Content 1",
                "author": "David Finch",
                "creation_date": "2017-11-14 12:00:08",
                "uuid": "ae1654d0-122d-11e8-ac70-b9cafc1ae222",
                "url": https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/ae1654d0-122d-11e8-ac70-b9cafc1ae222"
            },
            {
                "mime_type": "video",
                "title": "Content 2",
                "author": "Joseph Green",
                "creation_date": "2017-12-05 13:00:05",
                "uuid": "a32d7340-122d-11e8-86b1-0fd0c796e4a6",
                "url": https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/a32d7340-122d-11e8-86b1-0fd0c796e4a6"
            },
            {
                "mime_type": "video",
                "title": "Content 3",
                "author": "Mary White",
                "creation_date": "2017-08-07 11:00:02",
                "uuid": "efd82270-122c-11e8-bcaf-bb1d762cf37f",
                "url": https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents/efd82270-122c-11e8-bcaf-bb1d762cf37f"
            },
            ...
        ],
        "links": {
            "first": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents?page=0",
            "last": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents?page=4",
            "prev": null,
            "next": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents?page=1"
        },
        "meta": {
            "current_page": 0,
            "from": 0,
            "to": 4,
            "last_page": 4,
            "path": "https://backend.nuvolar.it/api/v2/domains/c9cec0a0-119d-11e8-80c4-2dddfbbc8e80/contents",
            "per_page": 5,
            "total": 23
        }
    }
Response  401
HideShow
Body
Unauthenticated.
Response  403
HideShow
Body
Access denied.
Response  404
HideShow
Body
Not found.

Generated by aglio on 15 Feb 2018