API

Last updated 07/01/2016

Welcome to the wonderful world of the HeyUpdate API documentation.

Making a request

All API requests must use the base URL https://api.heyupdate.com.

HTTP Verbs

Where possible, the API strives to use appropriate HTTP verbs for each action.

Verb Description
GET Used for retrieving resources.
POST Used for creating resources.
PATCH Used for updating resources.
DELETE Used for deleting resources.

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

$ curl -i https://api.heyupdate.com/updates?page=2

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json:

$ curl -X POST \
  -H 'Authorization: Bearer OAUTH-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"message": "I used the API"}' \
  https://api.heyupdate.com/updates

Root Endpoint

You can issue a GET request to the root endpoint to get all the endpoints that the API currently supports.

$ curl https://api.heyupdate.com

Authentication

There are two ways to authenticate with the API. Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private information to unauthorized users.

OAuth2 Token (sent in a header)

$ curl -H Authorization: Bearer OAUTH-TOKEN https://api.heyupdate.com

OAuth2 Token (sent as a parameter)

$ curl https://api.heyupdate.com?access_token=OAUTH-TOKEN

Personal API tokens can be generated from your user settings page and work in the same way as an OAuth2 access token.

Updates

Create an update

This will create a new update in your timeline.

POST /updates

Parameters

Name> Type Description
message string Required The message to be posted
timestamp datetime The date to post the update for. Must be either Y-m-d or ISO 8601 format.
user string The ID or email of user to post the update as. Defaults to current user. Only allowed for requests authenticated as an admin user.

Example

{
    "message": "I used the API"
}

Response

Status: 201 Created
Location: https://api.heyupdate.com/updates/11672

{
    "id": "11672",
    "timestamp": "2015-08-24T07:00:00+00:00",
    "created_at": "2015-08-24T07:00:00+00:00",
    "updated_at": "2015-08-24T07:00:00+00:00",
    "user": {
        "id": "3008",
        "email": "tom@heyupdate.com",
        "name": "Tom Graham"
    },
    "team": {
        "id": "10317",
        "name": "Demo"
    },
    "message": "I used the API"
}

Edit an update

PATCH /updates/:id

Parameters

Name> Type Description
message string The message to be posted
timestamp datetime The date to post the update for. Must be either Y-m-d or ISO 8601 format.

Example

PATCH /updates/11672

{
    "message": "I used the API to edit this status"
}

Response

Status: 200 OK

{
    "id": "11672",
    "timestamp": "2015-08-24T07:00:00+00:00",
    "created_at": "2015-08-24T07:00:00+00:00",
    "updated_at": "2015-08-24T10:12:00+00:00",
    "user": {
        "id": "3008",
        "email": "tom@heyupdate.com",
        "name": "Tom Graham"
    },
    "team": {
        "id": "10317",
        "name": "Demo"
    },
    "message": "I used the API to edit this status"
}