API Response Structure

This page contains detailed information about the structure of the APITube API response, including description of all fields and their possible values.

General response structure

All APITube responses are returned in JSON format and have the following general structure:

json

{
    "status": "ok",
    "page": 1,
    "path": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=2",
    "has_next_pages": true,
    "next_page": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=3",
    "has_previous_page": false,
    "previous_page": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1",
    "export": {
        "json": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=json",
        "xlsx": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=xlsx",
        "csv": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=csv",
        "tsv": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=tsv",
        "xml": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=xml"
    },
    "request_id": "5978d89c-46f6-4ab4-b65c-8b4a6000d4ac",
    "results": [
        // Array of articles
    ]
}

Main response fields

Field	Type	Description
`status`	string	Request status. Possible values: "ok" (request successful) or "error" (an error occurred).
`page`	integer	Current page of results.
`path`	string	Full URL of the current API request, including all request parameters.
`has_next_pages`	boolean	Flag indicating the presence of next pages of results (true - there are next pages).
`next_page`	string	Full URL to get the next page of results. Absent if `has_next_pages` is false.
`has_previous_page`	boolean	Flag indicating the presence of previous pages of results (true - there are previous pages).
`previous_page`	string	Full URL to get the previous page of results. Absent if `has_previous_page` is false.
`export`	object	Object with URLs for exporting results in various formats (json, xlsx, csv, tsv, xml).
`request_id`	string	Unique request identifier for tracking and debugging.
`results`	array	Array with request results (articles).

Article object fields

Each article in the results array has the following structure:

json

{
    "id": "Unique article ID",
    "href": "URL of the original article",
    "published_at": "Publication date and time in ISO 8601 format",
    "title": "Article title",
    "description": "Brief article description",
    "body": "Full article text",
    "language": "Article language (ISO 639-1 code)",
    "author": {
        "id": "Author ID",
        "name": "Author name"
    },
    "image": "URL of the main article image",
    "categories": [
        {
            "id": "Category ID",
            "name": "Category name",
            "score": "Category relevance score for the article",
            "taxonomy": "Category taxonomy name",
            "links": {
                "self": "URL to get information about the category"
            }
        }
    ],
    "topics": "Array of topics related to the article",
    "industries": [
        {
            "id": "Industry ID",
            "name": "Industry name",
            "links": {
                "self": "URL to get information about the industry"
            }
        }
    ],
    "entities": [
        {
            "id": "Entity ID",
            "name": "Entity name",
            "links": {
                "self": "URL to get information about the entity",
                "wikipedia": "Link to Wikipedia article",
                "wikidata": "Link to entity in Wikidata"
            },
            "types": "Array of entity types (human, location, organization, etc.)",
            "language": "Entity language",
            "frequency": "Frequency of entity mentions in the article",
            "title": {
                "pos": "Array of entity mention positions in the title"
            },
            "body": {
                "pos": "Array of entity mention positions in the article body"
            }
        }
    ],
    "source": {
        "id": "Source ID",
        "domain": "Source domain",
        "home_page_url": "URL of the source homepage",
        "type": "Source type (news, blog, etc.)",
        "rankings": {
            "opr": "Source ranking"
        },
        "location": {
            "country_name": "Source country name",
            "country_code": "Source country code (ISO 3166-1 alpha-2)"
        },
        "favicon": "Source favicon URL"
    },
    "sentiment": {
        "overall": {
            "score": "Overall article sentiment score",
            "polarity": "Textual representation of sentiment (positive, negative, neutral)"
        },
        "title": {
            "score": "Title sentiment score",
            "polarity": "Textual representation of title sentiment"
        },
        "body": {
            "score": "Article body sentiment score",
            "polarity": "Textual representation of body sentiment"
        }
    },
    "summary": [
        {
            "sentence": "Key sentence from the article",
            "sentiment": {
                "score": "Sentence sentiment score",
                "polarity": "Textual representation of sentiment"
            }
        }
    ],
    "keywords": "Array of article keywords",
    "links": "Array of URLs mentioned in the article",
    "media": [
        {
            "url": "Media file URL",
            "type": "Media file type (image, video, etc.)",
            "format": "Media file format (jpeg, png, mp4, etc.)"
        }
    ],
    "story": {
        "id": "Story ID",
        "uri": "URL to get information about the story"
    },
    "is_duplicate": "Flag indicating if the article is a duplicate",
    "is_paywall": "Flag indicating if the article is behind a paywall",
    "sentences_count": "Number of sentences in the article",
    "paragraphs_count": "Number of paragraphs in the article",
    "words_count": "Number of words in the article",
    "characters_count": "Number of characters in the article"
}

Detailed description of article fields

Field	Type	Description
`id`	integer	Unique article identifier in the APITube system.
`href`	string	URL of the original article.
`title`	string	Article headline.
`description`	string	Brief description or annotation of the article. May be absent for some articles.
`body`	string	Full article text without HTML tags.
`published_at`	string	Date and time of article publication in ISO 8601 format.
`language`	string	Article language in ISO 639-1 format (two-letter code).
`author`	object	Information about the article author.
`image`	string	URL of the main article image. May be absent for some articles.
`categories`	array	Array of categories the article belongs to.
`topics`	array	Array of topics related to the article.
`industries`	array	Array of industries related to the article content.
`entities`	array	Array of objects with information about entities (people, places, organizations, etc.) mentioned in the article.
`source`	object	Information about the article source.
`sentiment`	object	Article sentiment assessment.
`summary`	array	Array of objects containing key sentences from the article with their sentiment assessment.
`keywords`	array	Array of keywords extracted from the article.
`links`	array	Array of URLs mentioned in the article.
`media`	array	Array of objects containing information about media files (images, videos) related to the article.
`story`	object	Information about the story the article belongs to (id and uri).
`is_duplicate`	boolean	Indicates if the article is a duplicate of another article.
`is_paywall`	boolean	Indicates if the article is behind a paywall.
`sentences_count`	integer	Number of sentences in the article.
`paragraphs_count`	integer	Number of paragraphs in the article.
`words_count`	integer	Number of words in the article.
`characters_count`	integer	Number of characters in the article.

Detailed description of nested objects

Category object

json

{
    "id": "IAB19",
    "name": "Technology & Computing",
    "score": 0.5,
    "taxonomy": "iab-qag",
    "links": {
        "self": "https://api.apitube.io/v1/news/category/iab-qag/IAB19"
    }
}

Field	Type	Description
`id`	string	Unique category identifier.
`name`	string	Category name.
`score`	float	Category relevance score for the article (from 0 to 1).
`taxonomy`	string	Name of the taxonomy the category belongs to.
`links`	object	Object with links related to the category.

Industry object

json

{
    "id": 1067,
    "name": "Sporting event",
    "links": {
        "self": "https://api.apitube.io/v1/news/industry/1067"
    }
}

Field	Type	Description
`id`	integer	Unique industry identifier.
`name`	string	Industry name.
`links`	object	Object with links related to the industry.

Entity object

json

{
    "id": 798377,
    "name": "Juan Medina",
    "links": {
        "self": "https://api.apitube.io/v1/news/entity/798377",
        "wikipedia": "https://en.wikipedia.org/wiki/Juan_Medina",
        "wikidata": "https://www.wikidata.org/wiki/Q5573426"
    },
    "types": ["human"],
    "language": "en",
    "frequency": 1,
    "title": {
        "pos": [{
            "start": 102,
            "end": 113
        }]
    },
    "body": {
        "pos": [{
            "start": 102,
            "end": 113
        }]
    }
}

Field	Type	Description
`id`	integer	Unique entity identifier.
`name`	string	Entity name.
`links`	object	Object with links to external resources related to the entity (API, Wikipedia, Wikidata).
`types`	array	Array of entity types (e.g., "human", "location", "organization").
`language`	string	Entity language.
`frequency`	integer	Frequency of entity mentions in the article.
`title`	object	Information about entity mention positions in the article title.
`body`	object	Information about entity mention positions in the article body.

Source object

json

{
    "id": 8540,
    "domain": "sports.inquirer.net",
    "home_page_url": "https://sports.inquirer.net",
    "type": "news",
    "rankings": {
        "opr": 5
    },
    "location": {
        "country_name": "Philippines",
        "country_code": "ph"
    },
    "favicon": "https://www.google.com/s2/favicons?domain=https://sports.inquirer.net"
}

Field	Type	Description
`id`	integer	Unique source identifier.
`domain`	string	Source domain.
`home_page_url`	string	URL of the source homepage.
`type`	string	Source type (e.g., "news", "blog").
`rankings`	object	Source ratings and metrics.
`location`	object	Information about the geographic location of the source.
`favicon`	string	URL of the source favicon.

Sentiment object

json

{
    "overall": {
        "score": -0.01,
        "polarity": "neutral"
    },
    "title": {
        "score": -0.09,
        "polarity": "negative"
    },
    "body": {
        "score": 0.07,
        "polarity": "positive"
    }
}

Field	Type	Description
`overall`	object	Overall article sentiment assessment.
`title`	object	Article title sentiment assessment.
`body`	object	Article body sentiment assessment.

Each sentiment object contains:

score (float): numerical sentiment score (from -1 to 1, where negative values correspond to negative sentiment, and positive values to positive sentiment).
polarity (string): textual representation of sentiment ("positive", "negative", "neutral").

Media object

json

{
    "url": "https://sports.inquirer.net/files/2025/04/2025-04-24T150824Z_910329377_UP1EL4O161ZT2_RTRMADP_3_TENNIS-MADRID-620x420.jpg",
    "type": "image",
    "format": "jpeg"
}

Field	Type	Description
`url`	string	Media file URL.
`type`	string	Media file type (e.g., "image", "video").
`format`	string	Media file format (e.g., "jpeg", "png", "mp4").

Error response

In case of an error, the API returns a response with status "error" and additional information about the error:

json

{
  "status": "error",
  "code": "invalid_api_key",
  "message": "Your API key is invalid or missing."
}

Field	Type	Description
`status`	string	Always "error" in case of an error.
`code`	string	Error code.
`message`	string	Human-readable error message.

Error codes

Code	HTTP status	Description
`invalid_api_key`	401	Invalid or missing API key.
`unauthorized`	401	Insufficient permissions to perform the request.
`quota_exceeded`	429	Request limit exceeded.
`invalid_parameter`	400	Invalid parameter value.
`missing_parameter`	400	Missing required parameter.
`internal_error`	500	Internal server error.

Pagination

For working with large datasets, the API uses pagination. By default, the first page of results is returned. To access other pages, use the page and limit/per_page parameters.

Example of pagination request:

https://api.apitube.io/v1/news/everything?title=technology&page=2&per_page=20

Response with pagination information:

json

{
  "status": "ok",
  "page": 2,
  "per_page": 20,
  "path": "https://api.apitube.io/v1/news/everything?title=technology&page=2&per_page=20",
  "has_next_pages": true,
  "next_page": "https://api.apitube.io/v1/news/everything?title=technology&page=3&per_page=20",
  "has_previous_page": true,
  "previous_page": "https://api.apitube.io/v1/news/everything?title=technology&page=1&per_page=20",
  "results": [
    // Article objects
  ]
}

API response example

json

{
  "status": "ok",
  "page": 1,
  "per_page": 2,
  "path": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1",
  "has_next_pages": true,
  "next_page": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=2",
  "has_previous_page": false,
  "export": {
    "json": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=json",
    "xlsx": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=xlsx",
    "csv": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=csv",
    "tsv": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=tsv",
    "xml": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=xml"
  },
  "request_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "results": [
    {
      "id": 12345678,
      "href": "https://example.com/tech/new-smartphone-release",
      "published_at": "2023-06-15T10:30:00Z",
      "title": "New XYZ Smartphone Makes Waves in the Market",
      "description": "XYZ Company has introduced a new flagship smartphone that significantly outperforms competitors in performance and camera quality.",
      "body": "Today, XYZ Company introduced its new flagship smartphone. The device is equipped with the latest generation processor and a revolutionary camera that, according to the manufacturer, is capable of taking professional quality photos even in low light conditions. Industry experts have already highly rated the novelty, noting its excellent performance and innovative features.",
      "language": "en",
      "author": {
        "id": 5678,
        "name": "John Smith"
      },
      "image": "https://example.com/images/xyz-smartphone.jpg",
      "categories": [
        {
          "id": "IAB19",
          "name": "Technology & Computing",
          "score": 0.8,
          "taxonomy": "iab-qag",
          "links": {
            "self": "https://api.apitube.io/v1/news/category/iab-qag/IAB19"
          }
        }
      ],
      "topics": [],
      "industries": [
        {
          "id": 456,
          "name": "Consumer Electronics",
          "links": {
            "self": "https://api.apitube.io/v1/news/industry/456"
          }
        }
      ],
      "entities": [
        {
          "id": 789,
          "name": "XYZ Company",
          "links": {
            "self": "https://api.apitube.io/v1/news/entity/789",
            "wikipedia": "https://en.wikipedia.org/wiki/XYZ_Company",
            "wikidata": "https://www.wikidata.org/wiki/Q12345"
          },
          "types": ["organization"],
          "language": "en",
          "frequency": 3,
          "title": {
            "pos": [
              {
                "start": 4,
                "end": 15
              }
            ]
          },
          "body": {
            "pos": [
              {
                "start": 6,
                "end": 17
              },
              {
                "start": 122,
                "end": 133
              }
            ]
          }
        }
      ],
      "source": {
        "id": 123,
        "domain": "example.com",
        "home_page_url": "https://example.com",
        "type": "news",
        "rankings": {
          "opr": 8
        },
        "location": {
          "country_name": "United States",
          "country_code": "us"
        },
        "favicon": "https://example.com/favicon.ico"
      },
      "sentiment": {
        "overall": {
          "score": 0.45,
          "polarity": "positive"
        },
        "title": {
          "score": 0.3,
          "polarity": "positive"
        },
        "body": {
          "score": 0.6,
          "polarity": "positive"
        }
      },
      "summary": [
        {
          "sentence": "Today, XYZ Company introduced its new flagship smartphone.",
          "sentiment": {
            "score": 0.2,
            "polarity": "positive"
          }
        },
        {
          "sentence": "Industry experts have already highly rated the novelty, noting its excellent performance and innovative features.",
          "sentiment": {
            "score": 0.8,
            "polarity": "positive"
          }
        }
      ],
      "keywords": ["smartphone", "XYZ", "technology"],
      "links": ["https://example.com/related/xyz-previous-model"],
      "media": [
        {
          "url": "https://example.com/images/xyz-smartphone.jpg",
          "type": "image",
          "format": "jpeg"
        },
        {
          "url": "https://example.com/videos/xyz-smartphone-preview.mp4",
          "type": "video",
          "format": "mp4"
        }
      ],
      "story": {
        "id": 9876,
        "uri": "https://api.apitube.io/v1/news/story/9876"
      },
      "is_duplicate": false,
      "is_paywall": false,
      "sentences_count": 3,
      "paragraphs_count": 1,
      "words_count": 60,
      "characters_count": 354
    }
  ]
}

Notes

Field availability: Some fields may be absent from the response depending on data availability for a specific article or the subscription plan used.
Date format: All dates in the API are returned in ISO 8601 format (e.g., "2023-06-15T10:30:00Z").
Content limitations: Depending on the subscription plan, the body field may contain the full text of the article or only a part of it.
Language and country: The language and country fields use standard ISO codes (ISO 639-1 for languages and ISO 3166-1 alpha-2 for countries).
Sentiment: The score value ranges from -1 to 1, where negative values correspond to negative sentiment, and positive values to positive sentiment.

Examples

Getting started

API Response Structure

General response structure

Main response fields

Article object fields

Detailed description of article fields

Detailed description of nested objects

Category object

Industry object

Entity object

Source object

Sentiment object

Media object

Error response

Error codes

API response example

Notes

API Response Structure ​

General response structure ​

Main response fields ​

Article object fields ​

Detailed description of article fields ​

Detailed description of nested objects ​

Category object ​

Industry object ​

Entity object ​

Source object ​

Sentiment object ​

Media object ​

Error response ​

Error codes ​

Pagination ​

API response example ​

Notes ​

API Response Structure

General response structure

Main response fields

Article object fields

Detailed description of article fields

Detailed description of nested objects

Category object

Industry object

Entity object

Source object

Sentiment object

Media object

Error response

Error codes

Pagination

API response example

Notes