Pushed API

The API lets you interact with Pushed from anything that can send an HTTP request. There are many things you can do with the API. For example:

  • Send notifications to all your subscribers
  • Schedule notifications to some of your subscribers
  • Subscribe users to your applications and channels
  • Fetch your notifications analytics
  • And much more!

Schema

All API access is over HTTPS, and accessed from the api.pushed.co domain. The relative path prefix /1/ indicates that we are currently using version 1 of the API.

Current endpoint is https://api.pushed.co/1/.

All data is sent and received as JSON.

Response Format

The response format for all requests is a JSON object.

Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates failure.

For example, trying to verify an authorization code that is valid will return the message:

{
  "response": {
      "type": "auth_code_valid",
      "message": "Authorization Code is valid."
   }
}

Client Errors

When a request fails, the response body is still JSON, but always contains the fields code and error which you can inspect to use for debugging.

For example, trying to verify an authorization code that is invalid will return the message:

{
  "error": {
      "type": "auth_code_invalid",
      "message": "Authorization Code is not valid."
    }
}

Timezones

Pushed timezone is set to UTC, so all dates will be offered in this timezone.

Credentials

There are three credentials methods to use the API. Depending on what you want to accomplish, you will need to add to your request the required credentials.

Target Based Credential: Using your Pushed app/channel credentials (app_key, app_secret & target_alias).

Pushed Api-Key Based: Using your Pushed account api_key.

OAuth-Credentials Based: Using the access_token genereated in the OAuth process.

No Credential Required: Some API calls does not require any credentials.

Which one to use? We know this could be a little tedious but security is a huge concern and that's the best way to ensure your account data and privacy. For each of the methods of the API you will se a badge of what credentials are required.

Quick Reference Available Methods

Sending Notifications

Endpoint Functionality
https://api.pushed.co/1/push Send Push Message

Authorization

Endpoint Functionality
https://api.pushed.co/1/oauth Request an Access Token
https://api.pushed.co/1/oauth/new Request an Authorization Code with an Access Token
https://api.pushed.co/1/oauth/verify Verify an Authorization Code
https://api.pushed.co/1/oauth Delete an Authorization Code

Subscription Management

Endpoint Functionality
https://api.pushed.co/1/subscribe Get user subscriptions
https://api.pushed.co/1/subscribe Subscribe user to an app or channel
https://api.pushed.co/1/subscribe Delete a user subscription
https://api.pushed.co/1/subscribe/invite Invite a user to subscribe to an app or channel

Applications Management

Endpoint Functionality
https://api.pushed.co/1/app List all applications
https://api.pushed.co/1/app Create new application
https://api.pushed.co/1/app/delete Delete an application

Channels Management

Endpoint Functionality
https://api.pushed.co/1/channel List all channels
https://api.pushed.co/1/channel Create new channel
https://api.pushed.co/1/channel/delete Delete a channel

Analytics

Endpoint Functionality
https://api.pushed.co/1/analytics Hooks for retrieving multiple stats

Sending Notifications

https://api.pushed.co/1/push

This method allows Pushed applications to send notifications programatically. There are four options to reach Pushed users (we called it targets): app, channel, user or pushed identifier. Depending on your needs you will have to provide specific parameter to the push call.

Parameter Name Type Required Description
app_key string Yes Your application key. You can find your app_key on the settings section of your application inside the developer portal.
app_secret string Yes Your application secret. You can find your app_secret on the settings section of your application inside the developer portal.
content string Yes The content of the notification. Max length is 140 characters. If your content is larger than 140 characters the API will return an error: message_is_too_large.
content_type string Optional The content type of the notification. Currently there's only one option available: url. If this parameter is specified then special behaviour is applied to notification in order to show it properly.
content_extra string Optional The extra content of the notification. Depending on content_type parameter should be filled with relevant data.
target_type string Yes The type of the destination. Allowed options: app, channel, user or pushed_id.
target_alias string Optional Only required when target_type != app. Depending on the target_type the target_alias must include different information.
access_token string Optional Only required when target_type = user. You can obtain this value when your application requests OAuth access.
pushed_id string Optional Only required when target_type = pushed_id.The Pushed Identifier string of the user.
curl -X POST -s \
  --form-string "app_key=your_app_key" \
  --form-string "app_secret=your_app_secret" \
  --form-string "target_type=your_target_type" \
  --form-string "content=Your notification content." \
  https://api.pushed.co/1/push

Sending notification to a Pushed Channel

If you need to send a notification to a certain user, you have two options: using PushedID or OAuth token. Below you can find an example of sending a push message using PushedID using our API:

curl -X POST -s \
  --form-string "app_key=your_app_key" \
  --form-string "app_secret=your_app_secret" \
  --form-string "target_type=channel" \
  --form-string "target_alias=your_app_or_channel_alias" \
  --form-string "content=Your notification content." \
  https://api.pushed.co/1/push

Sending notification to an specific user using Pushed ID

If you need to send a notification to a certain user, you have two options: using PushedID or OAuth token. Below you can find an example of sending a push message using PushedID using our API:

curl -X POST -s \
  --form-string "app_key=your_app_key" \
  --form-string "app_secret=your_app_secret" \
  --form-string "target_type=pushed_id" \
  --form-string "pushed_id=user_pushed_id" \
  --form-string "content=Your notification content." \
  https://api.pushed.co/1/push

Sending notification to an specific user using OAuth Protocol

If you need to send a notification to a certain user, you can get user permissions by setting up Pushed OAuth Protocol in your system. Once the user has established connection with Pushed and granted your app access you will receive an access_token. You can use this access_token to send notifications without the need to add further parameters. Very Important: Only apps can use access_token, channels are not allowed to use target_type = user.

Below you can find an example of sending a push message using the OAuth Token using our API:

curl -X POST -s \
  --form-string "app_key=your_app_key" \
  --form-string "app_secret=your_app_secret" \
  --form-string "access_token=access_token_code_given_by_pushed" \
  --form-string "target_type=user" \
  --form-string "target_alias=your_channel_alias" \
  --form-string "content=Your notification content." \
  https://api.pushed.co/1/push

Authorization

oauth https://api.pushed.co/1/oauth

This method allows you to create the page where the user can authorize your Pushed app to access several information on their account. Remember that users can revoke permisions at any time.

Parameter Name Type Required Description
client_id string Yes Your application key. You can find your app_key on the settings section of your application inside the developer portal.
redirect_uri string Yes The URL Pushed will use to callback with the authorization details response.

oauth/access_token https://api.pushed.co/1/oauth/access_token

This method is used to exchange the code provided in https://api.pushed.co/1/oauth an access token. You should store the given access_token in your system so you can send interact with Pushed API methods at any time.

Parameter Name Type Required Description
code string Yes The code provided by https://api.pushed.co/1/oauth.

oauth/verify https://api.pushed.co/1/oauth/verify

This method allows you to check if an access_token is valid. This method shoudl be used to check permissions in case you are having issues with the access_token. Remember that users can revoke permisions at any time.

Parameter Name Type Required Description
access_token string Yes The access_token provided in https://api.pushed.co/1/oauth/access_token.

oauth https://api.pushed.co/1/oauth

Remove a previous access_token.

Parameter Name Type Required Description
access_token string Yes The access_token you want to delete provided in https://api.pushed.co/1/oauth/access_token.

Subscription Management

subscription https://api.pushed.co/1/subscription

This method allows you to list all subscriptions from a user. To use this method you need an OAuth access token. Learn More.

Parameter Name Type Required Description
access_token string Yes The code provided by https://api.pushed.co/1/oauth.
Example of a valid subscription response listing subscriptions:
{
  "response": {
    "type": "user_subscriptions_fetched",
    "message": "User subscriptions fetched.",
    "data": {
        {
            "subscription_alias": "CqVGmwordX",
            "source_type": "app",
            "created_at": {
                "date": "2016-08-23 10:48:25.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "source_alias": "abc123",
            "source_name": "Name of the app",
            "source_icon": "https://s3-eu-west-1.amazonaws.com/pushed.co/media/pushed.png",
            "source_permalink": "https://pushed.co/discover/abc123",
        }
    }
  }
}

subscription https://api.pushed.co/1/subscription

This method allows you to subscribe user from one of your sources (app or channel). To use this method you need an OAuth access token. Learn More.

Parameter Name Type Required Description
access_token string Yes The code provided by https://api.pushed.co/1/oauth.
source_alias string Yes The alias of your source (app or channel).
source_type string Yes Allowed options: app or channel.
Example of a valid subscription delete response:
{
  "response": {
    "type": "subscription_deleted",
    "message": "Subscription to Pushed Demo App deleted successfully.",
  }
}

subscription https://api.pushed.co/1/subscription

This method allows you to unsubscribe user from one of your sources (app or channel). To use this method you need an OAuth access token. Learn More.

Parameter Name Type Required Description
access_token string Yes The code provided by https://api.pushed.co/1/oauth.
subscription_alias string Yes The subscription_alias provided by https://api.pushed.co/1/subscribe.
Example of a valid subscription delete response:
{
  "response": {
    "type": "subscription_created",
    "message": "Subscription to Pushed Demo App created successfully.",
        "data": {
        {
            "subscription_alias": "CqVGmwordX",
        }
    }
  }
}

subscription/invite https://api.pushed.co/1/subscription/invite

This method allows you to invite users to subscribe to one of your sources (app or channel).

Parameter Name Type Required Description
app_key string Yes Your application key. You can find your app_key on the settings section of your application inside the developer portal.
app_secret string Yes Your application secret. You can find your app_secret on the settings section of your application inside the developer portal.
source_type string Yes Allowed options: app or channel.
source_alias string Optional Only required when source_type != app.
emails string Yes List of comma separated emails to send invitations to.
curl -X PUT -s \
  --form-string "app_key=your_app_key" \
  --form-string "app_secret=your_app_secret" \
  --form-string "source_type=your_source_type" \
  --form-string "source_alias=your_app_or_channel_alias" \
  --form-string "emails=emails_list_comma_separated" \
  https://api.pushed.co/1/subscription/invite
Example of a valid subscription/invite response:
{
  "response": {
    "type": "invitations_created_successfully",
    "message": "Invitations created successfully.",
        "data": {
        {
            "count": 1,
        }
    }
  }
}

Applications Management

https://api.pushed.co/1/app

This method lists all of your applications.

Parameter Name Type Required Description
No parameters required

Example of a valid app response listing apps:

{
  "response": {
    "type": "account_apps_fetched_successfully",
    "message": "Account apps fetched successfully.",
    "data": {
      "apps": {
        {
          "name": "Pushed Demo App",
          "alias": "abc123",
          "public": 1,
          "only_members": 0,
          "icon": "https://s3-eu-west-1.amazonaws.com/pushed.co/static/apps/abc123/abc123.png",
          "created_at": "2014-09-17 18:57:59"
        }
      }
    }
  }
}

https://api.pushed.co/1/app PUT

This method allows you to create a new application.

Parameter Name Type Required Description
name string Yes App name.
description string Yes App description.
public boolean Optional Wether your app will be publicly available or not (Private by default).
icon_url string Optional App icon url (will be saved to Pushed).
tags string Optional Comma separated app tags.
supercategory string Optional App category. Options available: Pushed Picks, News, Tech & Science, Internet, Sports, Business, Design, Music, Films & TV, Travel, Food, Style.

https://api.pushed.co/1/app

This method removes an applications.

Parameter Name Type Required Description
alias string required App alias.

Channels Management

Available soon.

Analytics

Available soon.

 

 

Lastest Update: Wed, 26 Jul 2017 09:36:24