API Reference

Submit async query

POST /api/v2/query-async

Primary end-point for query Athena news database. Used in conjuction with /api/v2/get-results

Name	Value
Content-Type	application/json

Body

Name	Type	Description
query	string (required)	Query string
api_key	string (required)	Your Athena API key.
sites	array (optional)	Array of strings ["cnn.com","nytimes.com"]
start_date	date (optional)	Date in ISO 8601 format
end_date	date (optional)	Date in ISO 8601 format
toggle_state	string (optional)	All Articles or Encoded Articles
embeddings	boolean (optional [true / false])	Returns embeddings with articles
page	int (required)	Page to iterate through results
language	string (optional)	Defaults to 'all'. See supported languages

Response

Name	Type	Description
query_id	string	Used for querying job status and retrieving results from /api/v2/get-results
state	string	Query success or fail

Get results

POST /api/v2/get-results

End-point for retrieving query results fom Athena News API.

Name	Type	Description
query_id	string (required)	Use query id issued when submitting a query to /api/v2/query-async
api_key	string (required)	Your Athena API key.
page	int (optional)	Defaults to first page of results unless otherwise specified

Response

Name	Type	Description
totalResults	int	Number of results
articles	array (optional)	Array of articles
state	date (optional)	Query success, fail, or pending

Submit a query

POST /api/v2/query

End-point for querying Athena news database. Works best with smaller time-frame queries (7 day time frame)

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description
query	string (required)	Query string
api_key	string (required)	Your Athena API key.
sites	array (optional)	Array of strings ["cnn.com","nytimes.com"]
start_date	date (optional)	Date in ISO 8601 format
end_date	date (optional)	Date in ISO 8601 format
toggle_state	string (optional)	All Articles or Encoded Articles
embeddings	boolean (optional [true / false])	Returns embeddings with articles
page	int (required)	Page to iterate through results
language	string (optional)	defaults to 'all'. See supported languages

Response

Name	Type	Description
totalResults	string (required)	Query string
articles	array (optional)	Array of articles
state	date (optional)	Query success or fail

Article Details

Response

Name	Type	Description
datePublished	string	Publish date of article
title	array	Article title
description	date	Article description
embeddings	array	Array of containing embeddings for title and description.
entities	array	Array of entities identified in the article
entity_relationships	array	Array of relationships identified between entities in the article.
image	string	String for article thumbnail
topics	array	Array of three primary topics
site	string	Site
score	float	Relevancy score

200

{
    "results": {
        "articles": [
            {
                "_id": "6734053d6e3c81cee1dcdf90",
                "datePublished": "Wed, 13 Nov 2024 01:44:17 GMT",
                "description": "President-elect Donald Trump has officially named Elon Musk to head the newly created 'Department of Government Efficiency.'",
                "entities": null,
                "entity_relationships": null,
                "image": [],
                "score": 17.239036560058594,
                "site": "dailymail.co.uk",
                "title": "Trump names Elon Musk and Vivek Ramaswamy to head Department of Government Efficiency - 'Manhattan Project of our time'",
                "topics": null
            },
            ...
        ],
        "queryId": "673407989980176f37ba87ca",
        "totalArticles": 1274
    },
    "state": "SUCCESS"
}

400

{
    "error": "not authorized"
}

500

{
    "state": "FAILED"
}