API Reference

The Hooks Data API is an interface for querying information from datasources and manage user hooks and subscriptions.

Authentication

Authenticate your requests by providing an API key which identifies a single user.

We prefer API key to be sent in the Authorization HTTP header of your outbound requests. However, you may also pass it in all API calls as a parameter called api_key.

Methods

Get user

[GET]

https://api.hooksdata.io/v1/me?api_key=API_KEY

Returns information associated to an account.

Authentication

Sample request

curl --request GET \
  --url 'https://api.hooksdata.io/v1/me?api_key=8aFBKmugwDvJvwia-_ioOCYVX_JIL7DLSdGtsuatukuIp8fvMTQ5Mg'

Sample response

{
  "status": "ok",
  "user": {
    "id": 1492,
    "email": "john@doe.com",
    "api_key": "8aFBKmugwDvJvwia-_ioOCYVX_JIL7DLSdGtsuatukuIp8fvMTQ5Mg",
    "updated_at": "2018-02-28T16:33:03Z",
    "created_at": "2018-02-14T12:28:05Z"
  }
}

Get user timeline

[GET]

https://api.hooksdata.io/v1/me/timeline?api_key=API_KEY

Returns a collection of the most recent items sent to the user.

The timeline returned is the equivalent of the one seen on the dashboard.

This method can only return up to 40 of a user’s most recent sent items. Optional parameters offset and limit should be used in order to paginate elements.

Authentication

Sample request

curl --request GET \
  --url 'https://api.hooksdata.io/v1/me/timeline?api_key=8aFBKmugwDvJvwia-_ioOCYVX_JIL7DLSdGtsuatukuIp8fvMTQ5Mg'

Sample response

{
  "status": "ok",
  "items": [
    {
      "_created_at": "2018-03-03T19:15:05Z",
      "_entity_type": "SoccerGame",
      "_id": "SoccerGame_490444",
      "_subscription": {
        "id": 50008,
        "user_id": 1492,
        "description": "Real Madrid starts within 30 minutes",
        "alias": "real_madrid_within30",
        "datasource": "SoccerGames",
        "query": "SELECT * FROM SoccerGames WHERE (home_team.team_name LIKE '%real madrid%' OR away_team.team_name LIKE '%real madrid%') AND start_datetime.countdown < 1800",
        "updated_at": "2018-02-22T15:27:17Z",
        "created_at": "2018-02-22T15:27:16Z"
      },
      "away_score": null,
      "away_team": {
        "_entity_type": "SoccerTeam",
        "_id": "SoccerTeam_2922",
        "espn_id": 2922,
        "id": "SoccerTeam_2922",
        "logo_url": "http://a.espncdn.com/combiner/i?img=/i/teamlogos/soccer/500/2922.png&h=500",
        "team_name": "Getafe"
      },
      "competition": "Spanish Primera División",
      "game_id": "490444",
      "home_score": null,
      "home_team": {
        "_entity_type": "SoccerTeam",
        "_id": null,
        "team_name": "Real Madrid"
      },
      "link": "http://m.espn.go.com/soccer/gamecast?gameId=490444&lang=EN&wjb=",
      "start_datetime": {
        "countdown": 1802,
        "datetime": "2018-03-03T19:45:00+0000",
        "timestamp": 1520106300
      },
      "status": "FUTURE",
      "timestamp": 1520106300
    }
  ]
}

Create a subscription

[POST]

https://api.hooksdata.io/v1/subscriptions?api_key=API_KEY

Creates a new subscription given a datasource and a query criteria. All new matching items will be inserted into user’s timeline and sent to all preconfigured hooks.

Optionally user may specify a human readable description and an alias identifier string. This last could be used later to refererence the new created subscription across API methods, instead of using subscription identifier.

Alias must be unique, and can only contain lowercased alphanumeric, _ and - characters. If none is specified a default one will be assigned.

Authentication

Request Parameters

application/json

name type description required
description string A human readable description no
alias string Subscription alias no
query string HQL query yes

Sample Request

curl --request POST \
  --url 'https://api.hooksdata.io/v1/subscriptions?api_key=8aFBKmugwDvJvwia-_ioOCYVX_JIL7DLSdGtsuatukuIp8fvMTQ5Mg' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "The Verge RSS updates",
  "alias": "the_verge_rss",
  "query": "SELECT * FROM RSS('\''https://www.theverge.com'\'')"
}'

Sample Response

{
  "status": "ok",
  "subscription": {
    "id": 50020,
    "user_id": 1492,
    "description": "The Verge RSS updates",
    "alias": "the_verge_rss",
    "datasource": "RSS",
    "query": "SELECT * FROM RSS('https://www.theverge.com')",
    "updated_at": "2018-02-28T17:10:19Z",
    "created_at": "2018-02-28T17:10:19Z"
  }
}

Get a subscription

[GET]

https://api.hooksdata.io/v1/subscriptions/:subscription_id?api_key=API_KEY

Retrieves a specific subscription.

Authentication

Sample Request

curl --request GET \
  --url 'https://api.hooksdata.io/v1/subscriptions/the_verge_rss?api_key=8aFBKmugwDvJvwia-_ioOCYVX_JIL7DLSdGtsuatukuIp8fvMTQ5Mg'

Sample Response

{
    "status": "ok",
    "subscription": {
        "id": 50020,
        "user_id": 1492,
        "description": "The Verge RSS updates",
        "alias": "the_verge_rss",
        "datasource": "RSS",
        "query": "SELECT * FROM RSS('https://www.theverge.com')",
        "updated_at": "2018-02-28T17:10:19Z",
        "created_at": "2018-02-28T17:10:19Z"
    }
}

Get all subscriptions

[GET]

https://api.hooksdata.io/v1/subscriptions?api_key=API_KEY

Retrieves all subscriptions.

Authentication

Sample request

curl --request GET \
  --url 'https://api.hooksdata.io/v1/subscriptions?api_key=8aFBKmugwDvJvwia-_ioOCYVX_JIL7DLSdGtsuatukuIp8fvMTQ5Mg'

Sample response

{
    "status": "ok",
    "subscriptions": [
        {
            "id": 50020,
            "user_id": 1492,
            "description": "The Verge RSS updates",
            "alias": "the_verge_rss",
            "datasource": "RSS",
            "query": "SELECT * FROM RSS('https://www.theverge.com')",
            "updated_at": "2018-02-28T17:10:19Z",
            "created_at": "2018-02-28T17:10:19Z"
        },
        {
            "id": 50021,
            "user_id": 1492,
            "description": "Tell me when it rains in Orihuela",
            "alias": "rains_in_orihuela",
            "datasource": "WeatherByCity",
            "query": "SELECT * FROM WeatherByCity(name = 'Orihuela') WHERE weather_conditions.main = 'Rain' AND is_current = true",
            "updated_at": "2018-03-01T10:23:34Z",
            "created_at": "2018-03-01T10:23:34Z"
        }
    ]
}

Get subscription timeline

[GET]

https://api.hooksdata.io/v1/subscriptions/:subscription_id/timeline?api_key=API_KEY

Returns a collection of the most recent sent items associated to a specific subscription.

This method can only return up to 40 of a subscription most recent sent items. Optional parameters offset and limit should be used in order to paginate elements.

Authentication

Sample request

curl --request GET \
  --url 'https://api.hooksdata.io/v1/subscriptions/the_verge_rss/timeline?api_key=8aFBKmugwDvJvwia-_ioOCYVX_JIL7DLSdGtsuatukuIp8fvMTQ5Mg'

Sample response

{
    "status": "ok",
    "items": [
        {
            "_created_at": "2018-03-03T22:05:56Z",
            "_entity_type": "FeedItem",
            "_id": "FeedItem_https://www.theverge.com/_https://www.theverge.com/2018/3/3/17059848/tide-meme-very-not-funny",
            "_subscription": {
                "id": 50020,
                "user_id": 1492,
                "description": "The Verge RSS updates",
                "alias": "the_verge_rss",
                "datasource": "RSS",
                "query": "SELECT * FROM RSS('https://www.theverge.com')",
                "updated_at": "2018-02-28T17:10:19Z",
                "created_at": "2018-02-28T17:10:19Z"
            },
            "authors": [
                {
                    "email": null,
                    "link": null,
                    "name": "Kaitlyn Tiffany"
                }
            ],
            "categories": [],
            "content": "\n<img alt=\"\" data-portal-copyright=\"\" data-has-syndication-rights=\"1\" data-focal-region=\"x1:227,y1:160,x2:313,y2:246\" src=\"https://cdn.vox-cdn.com/thumbor/eLFYh_ESDct5lZdESjVFj-94lrQ=/0x23:540x383/1310x873/cdn.vox-cdn.com/uploads/chorus_image/image/58889727/download.0.jpeg\"><p>The idea of ingesting a Tide Pod used to be a little bit funny. </p>\n<p>For example, when <em>The New York Daily News</em> printed a comment from Senator Chuck Schumer under a <a href=\"http://www.nydailynews.com/new-york/schumer-newfangled-detergent-pods-candy-article-1.1155442\">rudely ageist headline</a> in September 2012. He had recently been informed that 40 children in New York City had eaten Tide Pods and received medical attention for eating Tide Pods in the preceding five months. And he said, mostly unprovoked, “I saw one on my staffer’s desk and I wanted to eat it.” It’s good in print and it’s better out loud. “I saw one on my staffer’s desk and I wanted to eat it.”</p>\n<p>Very funny! Especially if you’re familiar with and entertained by Chuck Schumer’s general countenance and mannerisms, which — as a regular attendee of the Labor Day parade in Crown...</p>\n  <p>\n    <a href=\"https://www.theverge.com/2018/3/3/17059848/tide-meme-very-not-funny\">Continue reading…</a>\n  </p>\n",
            "contributors": [],
            "description": "\n<img alt=\"\" data-portal-copyright=\"\" data-has-syndication-rights=\"1\" data-focal-region=\"x1:227,y1:160,x2:313,y2:246\" src=\"https://cdn.vox-cdn.com/thumbor/eLFYh_ESDct5lZdESjVFj-94lrQ=/0x23:540x383/1310x873/cdn.vox-cdn.com/uploads/chorus_image/image/58889727/download.0.jpeg\"><p>The idea of ingesting a Tide Pod used to be a little bit funny. </p>\n<p>For example, when <em>The New York Daily News</em> printed a comment from Senator Chuck Schumer under a <a href=\"http://www.nydailynews.com/new-york/schumer-newfangled-detergent-pods-candy-article-1.1155442\">rudely ageist headline</a> in September 2012. He had recently been informed that 40 children in New York City had eaten Tide Pods and received medical attention for eating Tide Pods in the preceding five months. And he said, mostly unprovoked, “I saw one on my staffer’s desk and I wanted to eat it.” It’s good in print and it’s better out loud. “I saw one on my staffer’s desk and I wanted to eat it.”</p>\n<p>Very funny! Especially if you’re familiar with and entertained by Chuck Schumer’s general countenance and mannerisms, which — as a regular attendee of the Labor Day parade in Crown...</p>\n  <p>\n    <a href=\"https://www.theverge.com/2018/3/3/17059848/tide-meme-very-not-funny\">Continue reading…</a>\n  </p>\n",
            "enclosures": [
                {
                    "bitrate": null,
                    "copyright": null,
                    "duration": null,
                    "handler": null,
                    "keywords": [],
                    "language": null,
                    "length": null,
                    "link": null,
                    "player": null,
                    "thumbnails": [],
                    "title": null,
                    "type": null
                }
            ],
            "feed": {
                "authors": [],
                "categories": [],
                "contributors": [],
                "copyright": null,
                "description": null,
                "language": "en",
                "links": [
                    "https://www.theverge.com/"
                ],
                "logo": {
                    "link": null,
                    "title": null,
                    "url": "https://cdn.vox-cdn.com/community_logos/52801/VER_Logomark_32x32..png"
                },
                "permalink": "https://www.theverge.com/",
                "title": "The Verge -  All Posts"
            },
            "id": "https://www.theverge.com/2018/3/3/17059848/tide-meme-very-not-funny",
            "last_update_date": {
                "countdown": -354,
                "datetime": "2018-03-03T22:00:02+0000",
                "timestamp": 1520114402
            },
            "links": [
                "https://www.theverge.com/2018/3/3/17059848/tide-meme-very-not-funny"
            ],
            "permalink": "https://www.theverge.com/2018/3/3/17059848/tide-meme-very-not-funny",
            "post_date": {
                "countdown": -354,
                "datetime": "2018-03-03T22:00:02+0000",
                "timestamp": 1520114402
            },
            "title": "The last joke is Tide Pods"
        }
    ]
}

Delete a subscription

[POST]

https://api.hooksdata.io/v1/subscriptions/:subscription_id/delete?api_key=API_KEY

Deletes a subscription.

Authentication

Sample request

curl --request POST \
  --url 'https://api.hooksdata.io/v1/subscriptions/:subscription_id/delete?api_key=API_KEY'

Sample response

{
  "status": "ok"
}

Create a hook

[POST]

https://api.hooksdata.io/v1/hooks?api_key=API_KEY

Use this method to specify a url and receive incoming items via an outgoing webhook. Whenever there is a new item that matches any of the account subscription queries, we will send a POST request to the specified url containing a JSON-serialized payload.

Authentication

Request Parameters

application/json

name type description required
type string Always webhook yes
url string Outgoing webhook url yes

Sample request

curl --request POST \
  --url 'https://api.hooksdata.io/v1/hooks?api_key=bKpqCcSzr852PW0qbyMhqrORnrgj8DrIWRrnv6dj1qGbWqTS25Ip_TE0OTI' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "webhook",
  "url": "https://example.org/update"
}'

Sample response

{
  "status": "ok",
  "hook": {
    "id": 2014,
    "user_id": 1492,
    "status": "active",
    "type": "webhook",
    "info": {
      "url": "https://example.org/update"
    }
  }
}

Get a hook

[GET]

https://api.hooksdata.io/v1/hooks/:hook_id?api_key=API_KEY

Retrieves a specific hook.

Authentication

Sample request

curl --request GET \
  --url 'https://api.hooksdata.io/v1/hooks/2014?api_key=8aFBKmugwDvJvwia-_ioOCYVX_JIL7DLSdGtsuatukuIp8fvMTQ5Mg'

Sample response

{
  "status": "ok",
  "hook": {
    "id": 2014,
    "user_id": 1492,
    "status": "active",
    "type": "webhook",
    "info": {
      "url": "https://example.org/update"
    },
    "updated_at": "2018-02-28T17:20:42Z",
    "created_at": "2018-02-28T17:20:42Z"
  }
}

Get all hooks

[GET]

https://api.hooksdata.io/v1/hooks?api_key=API_KEY

Retrieves all hooks.

Authentication

Sample request

curl --request GET \
  --url 'https://api.hooksdata.io/v1/hooks?api_key=8aFBKmugwDvJvwia-_ioOCYVX_JIL7DLSdGtsuatukuIp8fvMTQ5Mg'

Sample response

{
  "status": "ok",
  "hooks": [
    {
      "id": 2013,
      "user_id": 1492,
      "status": "active",
      "type": "webhook",
      "info": {
        "url": "https://example.co/update"
      },
      "updated_at": "2018-02-28T17:18:36Z",
      "created_at": "2018-02-28T17:18:36Z"
    },
    {
      "id": 2014,
      "user_id": 1492,
      "status": "active",
      "type": "webhook",
      "info": {
        "url": "https://example.org/update"
      },
      "updated_at": "2018-02-28T17:20:42Z",
      "created_at": "2018-02-28T17:20:42Z"
    }
  ]
}

Delete a hook

[POST]

https://api.hooksdata.io/v1/hooks/:hook_id/delete?api_key=API_KEY

Deletes an specific hook.

Authentication

Sample request

curl --request POST \
  --url 'https://api.hooksdata.io/v1/subscriptions/the_verge_rss/delete?api_key=8aFBKmugwDvJvwia-_ioOCYVX_JIL7DLSdGtsuatukuIp8fvMTQ5Mg'

Sample response

{
  "status": "ok"
}

Query datasource

[POST]

http://api.hooksdata.io/v1/fetch

Filters items from a datasource applying an specific query. Alternatively this endpoint can also be invoked via GET method.

Request Parameters

application/json

name type description required
query string HQL query yes

Sample Request

curl --request POST \
  --url http://api.hooksdata.io/v1/fetch \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "SELECT * FROM SoccerGames WHERE home_team.team_name = '\''Levante'\'' AND status = '\''FINAL'\''"
}
'
curl --request GET \
  --url 'http://api.hooksdata.io/v1/fetch?query=SELECT%20%2A%20FROM%20SoccerGames%20WHERE%20home_team.team_name%20%3D%20%27Levante%27%20AND%20status%20%3D%20%27FINAL%27'

Sample Response

{
  "matches_count": 1,
  "items": [
    {
      "_entity_type": "SoccerGame",
      "_id": "SoccerGame_490443",
      "away_score": 1,
      "away_team": {
        "_entity_type": "SoccerTeam",
        "_id": "SoccerTeam_88",
        "espn_id": 88,
        "id": "SoccerTeam_88",
        "logo_url": "http://a.espncdn.com/combiner/i?img=/i/teamlogos/soccer/500/88.png&h=500",
        "team_name": "Espanyol"
      },
      "competition": "Spanish Primera División",
      "game_id": "490443",
      "home_score": 1,
      "home_team": {
        "_entity_type": "SoccerTeam",
        "_id": "SoccerTeam_1538",
        "espn_id": 1538,
        "id": "SoccerTeam_1538",
        "logo_url": "http://a.espncdn.com/combiner/i?img=/i/teamlogos/soccer/500/1538.png&h=500",
        "team_name": "Levante"
      },
      "link": "http://m.espn.go.com/soccer/gamecast?gameId=490443&lang=EN&wjb=",
      "start_datetime": null,
      "status": "FINAL"
    }
  ]
}