# Newslit News API
Integrate your Newslit briefs into your application or website through a single & simple HTTP REST API.

You can display a series of stories from a live report. Reports are created by adding relevant keywords (topics, filters & exclusions) and are updated every few hours with new content.

Within the API you can specify
- Number of stories to display
- The first paragraph of the story
- Image associated with the story
- Headline and url to the story
- Story source

To make any requests you’ll need an API account. API accounts are tied to a Newslit user account.

An API account has an API key. This key will give you access to reports for the respective user.

The following endpoints are currently available:
- [`GET /reports`](#List-Reports) - get a list of all reports tied to your API account
- [`GET /reports/:report_id`](#Get-Report) - get a specific report information (topics, filters, exclusions and any other metadata)
- [`GET /reports/:report_id/stories`](#Get-Report-Stories) - get stories from a specific report
- [`POST /reports`](#Add-Report) - create a new report, using all the filters available
- [`PUT /reports/:report_id`](#Update-Report) - update a specific report tied to your api account
- [`DELETE /reports/:report_id`](#Delete-Report) - delete a specific report tied to your api account

## Authentication
Authentication is handled with a simple API key. The API key should be attached to a request in the header field as `X-NewslitApiKey`.

curl -H "X-NewslitApiKey: YOUR_API_KEY" \
    -X GET "https://api.newslit.co/v1/reports"

## Response format
Responses return a json object. Successful responses will always have a `meta` field containing request metadata as well a `results` field containing any response data.

Relevant HTTP status codes are used where possible for every response.

## Errors
If something goes wrong with the request, we will return a relevant HTTP status code along side a json object containing an `error` field with a human readable description of what has gone wrong, `error_code` identifying the type of error returning and

For example, if a request supplies an incorrect API key you'll receive a `401 Unauthorized` code with the following response:

{
    "error": "Missing or invalid API key",
    "error_code": 401,
    "timestamp": 1518117367953
}

## Endpoints

### List Reports
`GET /reports` will return a list of all reports tied to your API account

#### Example request

curl -H "X-NewslitApiKey: YOUR_API_KEY" \
     -X GET "https://api.newslit.co/v1/reports"

#### Response
| Field | Type | Description |
| ------- | ------ | ------------- |
| reports|Array|Reports tied to the API Key. Each Report has the following fields:|
| id|String|The name of the Report|
| name|String|Title for the story|
| keywords|Array|A list of the keywords to include in this report|
| filters|Array|Matching stories **MUST** include at least one of these words|
| exclusions|Array|Matching stories must **NOT** include any of these words|
| date_added|String|Date when the report was added|
| report_stories_url|String|API URL endpoint to retrieve the report stories|

{
   "meta": {
       "code": 200,
       "size": 1,
       "timestamp": 1517624528958
   },
   "results": {
       "reports": [
           {
               "id": 9859071940,
               "name": "California Solar Industry",
               "keywords": [
                   "solar panels",
                   "solar power",
                   "solar energy"
               ],
               "filters": [
                   "California"
               ],
               "exclusions": [
               ],
               "date_added": "2019-07-02T04:06:23.000-08:00",
               "report_stories_url": "https://api.newslit.co/v1/reports/9859071940/stories",
           }
       ]
   }
}

- `200 OK` will be returned if the request was successful

### Get Report
`GET /reports/:report_id` will return the specific report for `report_id`

#### Example request

curl -H "X-NewslitApiKey: YOUR_API_KEY" \
     -X GET "https://api.newslit.co/v1/reports/9859071940"

#### Response
| Field | Type | Description |
| ----- | ---- | ----------- |
| reports | Array|a Report object which has the following fields:|
| id | String | |
| name | String | The name of the Report |
| keywords | Array | A list of the keywords to include in this report |
| filters | Arra y| Matching stories **MUST** include at least one of these words |
| exclusions | Array | Matching stories must **NOT** include any of these words |
| date_added | String | Date when the report was added|
| report_stories_url |String | API URL endpoint to retrieve the report stories |

{
   "meta": {
       "code": 200,
       "size": 1,
       "timestamp": 1517624528958
   },
   "results": {
       "report": {
           "id": 9859071940,
           "name": "California Solar Industry",
           "keywords": [
               "solar panels",
               "solar power",
               "solar energy"
           ],
           "filters": [
               "California"
           ],
           "exclusions": [
           ],
           "date_added": "2019-07-02T04:06:23.000-08:00",
           "report_stories_url": "https://api.newslit.co/v1/reports/9859071940/stories",
       }
   }
}

- `200 OK` will be returned if the request was successful

### Get Report Stories
`GET /reports/:report_id/stories` Returns a paginated array of stories for the given `report_id`

#### Example request

curl -H "X-NewslitApiKey: YOUR_API_KEY" \
     -X GET "https://api.newslit.co/v1/reports/9859071940/stories?count=1"

#### Response

{
   "meta": {
       "code": 200,
       "stories": {
           "next": "https://api.newslit.co/v1/news?query=bitcoin&count=1&offset=1",
           "size": 1,
           "offset": 0,
           "total_size": 3921,
           "count": 1
       },
       "size": 1,
       "timestamp": 1517624528958
   },
   "results": {
       "stories": [
           {
               "id": 9859071940,
               "url": "http://www.ft.com/content/c3c25960-080f-11e8-9650-9c0ad2d7c5b5"
               "title": "Bitcoin skids below $8,000",
               "excerpt": "Bitcoin's bad day has got even worse. The digital currency dropped below $8,000 on Friday for the first time since November 2017. The digital currency has come under intense pressure this year, crashing 60 per cent from the high it struck in…",
               "source": "Financial Times",
               "publicationDate": "2019-02-02T04:06:23.000-08:00",
               "language": "en",
               "imageUrl": "https://www.ft.com/__assets/creatives/brand-ft/icons/v3/open-graph.png",
           }
       ]
   }
}

- `200 OK` will be returned if the request was successful

### Add Report
`POST /reports` will add a new report. You must include a name and at least one keyword.

**Parameters**

| Field | Type | Required | Description |
| ----- | -----| -------- | ----------- |
| name | String | True | The name of the report |
| keywords| Array | True | A list of the keywords to include in this report |
| filters |Array | False | Matching stories **MUST** include at least one of these words |
| exclusions | Array | False | Matching stories must **NOT** include any of these words |

#### Example request

curl -H "X-NewslitApiKey: YOUR_API_KEY" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"name": "California Solar Industry","keywords": ["solar panels", "solar power", "solar energy"]}' \
     "https://api.newslit.co/v1/reports"

#### Response

{
     "meta": {
         "code": 201,
         "timestamp": 1517624528958
     },
     "results": {
         "id": 87,
         "report_api_url": "https://api.newslit.co/v1/reports/87"
     }
}

- `201 Created` will be returned if the request was successful

#### Status Codes

| Error code | Description |
| ---------- | ----------- |
| 1241 | Invalid or missing `name` |
| 1242 | Invalid or missing `keywords` |
| 1243 | Plan report limit exceeded |

### Update Report
`PUT /reports/:report_id` will update the report for the given `report_id`

#### Example request

curl -H "X-NewslitApiKey: YOUR_API_KEY" \
     -X PUT \
     -H "Content-Type: application/json" \
     -d '{"keywords": ["solar panels", "solar power", "solar energy"]}' \
     "https://api.newslit.co/v1/reports/9859071940"

#### Response

{
    "meta": {
        "code": 200,
        "timestamp": 1517624528958
    },
    "results": {
        "id": 9859071940,
        "report_api_url": "https://api.newslit.co/v1/reports/9859071940"
    }
}

- `200 OK` will be returned if the request was successful

#### Status Codes

| Error code | Description |
| ---------- | ----------- |
| 1240 | Invalid or missing `report_id` |
| 1241 | Invalid or missing `name` |
| 1242 | Invalid or missing `keywords` |

### Delete Report
`DELETE /reports/:report_id` will delete the report for the given `report_id`

#### Example request

curl -H "X-NewslitApiKey: YOUR_API_KEY" \
     -X DELETE "https://api.newslit.co/v1/reports/9859071940"

#### Response

HTTP/1.1 204 No Content

- `204 No Content` will be returned if the request was successful

#### Status Codes

| Error code | Description |
| ---------- | ----------- |
| 1240 | Invalid or missing `report_id` |