API Documentation

Version: 2.2.1

Getting Started

All API requests require an 'apikey' header with your organization's API key. If you'd like to use the API but don't have a key, contact dev@yellowdig.com and we'll create one for you.

you may wish to set your API key as an environment variable:

export API_KEY=your-api-key
all requests must provide the 'apikey' header:
curl -H "apikey: $API_KEY" https://api.yellowdig.com/v1/users

A Note About Scoped Access

Depending on how your API key was distributed, API requests may only return a subset of all boards or users in your organization. This is because certain API keys may be created with associated access restrictions. Contact your administration or dev@yellowdig.com if you'd like to change the scoping of your key. Future versions of Yellowdig will support key generation via the www.yellowdig.com.

Query Parameters

The Yellowdig API supports the following query parameters:

Thus, a query ranging from January 1st 2016 to February 1st 2016 would look like:

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/users?start=1451624400000&end=1454302800000

where the start and end parameters are unix timestamps

Api Methods

/events

all interaction data from your oganization

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/events

example response

[
    {
        "type": "pin",
        "action": "visited",
        "owner": {
            "id": 7220,
            "email": "dev@yellowdig.com",
            "name": "Test User",
            "role": "coadmin",
            "class_role": "instructor"
        },
        "actor": {
            "id": 7220,
            "email": "dev@yellowdig.com",
            "name": "Test User",
            "role": "coadmin",
            "class_role": "instructor"
        },
        "organization": {
            "id": 19,
            "name": "Yellowdig",
            "domain": "yellowdig.com",
            "category_id": 1
        },
        "pin": {
            "id": 33234,
            "activity": "visited",
            "title": "Internet freedom in India improved by 2 points in 2015: report",
            "body": "Internet freedom in India has improved slightly under the Narendra Modi-led government even as censorship and surveillance of the Web increased world over ",
            "web_url": "http://indianexpress.com/article/technology/tech-news-technology/internet-freedom-in-india-improved-by-2-points-in-2015-report/",
            "image_url": "http://images.indianexpress.com/2015/11/internet_new1.jpg?w=480",
            "tags": []
        },
        "board": {
            "id": 1328,
            "title": "Test Board (10th Aug 2015)",
            "category": "Communications"
        },
        "timestamp": "2015-12-06T00:10:50.937+00:00"
    }
]
/boards

all boards that belong to your organization

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/boards

example response

[
    {
        "id": 123,
        "title": "Intro to Classroom"
    },
    {
        "id": 124,
        "title": "Quantitative Research Methods"
    }
]
/users

all users in your organization

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/users

example response

[
    {
        "id": 123123,
        "first_name": "Dig",
        "last_name": "ud",
        "email": "dig.ud@yellowdig.com"
    },
    {
        "id": 123124,
        "first_name": "Yellow",
        "last_name": "Dig",
        "email": "yellow.dig@yellowdig.com"
    }
]
/events/board/:board-id

all interactions on a specified board

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/events/board/:board-id

example response

[
    {
        "type": "board",
        "action": "followed",
        "owner": {
            "id": 82,
            "email": "dev@yellowdig.com",
            "name": "My Name",
            "role": "coadmin",
            "class_role": "instructor"
        },
        "actor": {
            "id": 1665,
            "email": "dev@yellowdig.com",
            "name": "Tester",
            "role": "user",
            "class_role": "instructor"
        },
        "organization": {
            "id": 19,
            "name": "Yellowdig",
            "domain": "yellowdig.com",
            "category_id": 1
        },
        "board": {
            "id": 474,
            "title": "Test Board",
            "category": "Bookmarks"
        },
        "timestamp": "2015-12-09T07:53:29.174+00:00"
    }
]
/events/pins

all pins from your organization (from all boards)

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/events/pins

example response

[
    {
        "type": "pin",
        "action": "visited",
        "owner": {
            "id": 7220,
            "email": "dev@yellowdig.com",
            "name": "Dev User",
            "role": "coadmin",
            "class_role": "instructor"
        },
        "actor": {
            "id": 7220,
            "email": "dev@yellowdig.com",
            "name": "Dev User",
            "role": "coadmin",
            "class_role": "instructor"
        },
        "organization": {
            "id": 19,
            "name": "Yellowdig",
            "domain": "yellowdig.com",
            "category_id": 1
        },
        "pin": {
            "id": 33234,
            "activity": "visited",
            "title": "Internet freedom in India improved by 2 points in 2015: report",
            "body": "Internet freedom in India has improved slightly under the Narendra Modi-led government even as censorship and surveillance of the Web increased world over ",
            "web_url": "http://indianexpress.com/article/technology/tech-news-technology/internet-freedom-in-india-improved-by-2-points-in-2015-report/",
            "image_url": "http://images.indianexpress.com/2015/11/internet_new1.jpg?w=480",
            "tags": []
        },
        "board": {
            "id": 1328,
            "title": "Test Board (10th Aug 2015)",
            "category": "Communications"
        },
        "timestamp": "2015-12-06T00:10:50.937+00:00"
    }
]
/events/user/:user-id

get all interactions from a user by user-id

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/events/user/:user-id

example response

[
    {
        "type": "pin",
        "action": "visited",
        "owner": {
            "id": 7220,
            "email": "dev@yellowdig.com",
            "name": "Dev User",
            "role": "coadmin",
            "class_role": "instructor"
        },
        "actor": {
            "id": 7220,
            "email": "dev@yellowdig.com",
            "name": "Dev User",
            "role": "coadmin",
            "class_role": "instructor"
        },
        "organization": {
            "id": 19,
            "name": "Yellowdig",
            "domain": "yellowdig.com",
            "category_id": 1
        },
        "pin": {
            "id": 33234,
            "activity": "visited",
            "title": "Internet freedom in India improved by 2 points in 2015: report",
            "body": "Internet freedom in India has improved slightly under the Narendra Modi-led government even as censorship and surveillance of the Web increased world over ",
            "web_url": "http://indianexpress.com/article/technology/tech-news-technology/internet-freedom-in-india-improved-by-2-points-in-2015-report/",
            "image_url": "http://images.indianexpress.com/2015/11/internet_new1.jpg?w=480",
            "tags": []
        },
        "board": {
            "id": 1328,
            "title": "Test Board (10th Aug 2015)",
            "category": "Communications"
        },
        "timestamp": "2015-12-06T00:10:50.937+00:00"
    }
]
/board/:boardId/points

all users points on specified board

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/board/:boardId/points

example response

{
    "email1@yellowdig.com": {
        "user_id": 123,
        "board_id": 10,
        "email": "email1@yellowdig.com",
        "total_points": 25,
        "participation_score": 25
    },
    "email2@yellowdig.com": {
        "user_id": 881,
        "board_id": 10,
        "email": "email2@yellowdig.com",
        "total_points": 106,
        "participation_score": 100
    }
}
/user/:userId/points

all users points on boards they follow

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/user/:userId/points

example response

{
    "123124": {
        "user_id": 123124,
        "board_id": 12312873,
        "email": "email@yellowdig.com",
        "total_points": 48,
        "participation_score": 68
    },
    "123125": {
        "user_id": 123125,
        "board_id": 12312874,
        "email": "email2@yellowdig.com",
        "total_points": 49,
        "participation_score": 70
    }
}
/lti/:ltiId/points

all users points on board found via board LTI id

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/lti/:ltiId/points

example response

{
    "email1@yellowdig.com": {
        "user_id": 123,
        "board_id": 10,
        "email": "email1@yellowdig.com",
        "total_points": 25,
        "participation_score": 25
    },
    "email2@yellowdig.com": {
        "user_id": 881,
        "board_id": 10,
        "email": "email2@yellowdig.com",
        "total_points": 106,
        "participation_score": 100
    }
}
/course/:courseId/points

all users points on board found via canvas course id - (NOTE: this requires custom configuration)

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/course/:courseId/points

example response

{
    "email1@yellowdig.com": {
        "user_id": 123,
        "board_id": 10,
        "email": "email1@yellowdig.com",
        "total_points": 25,
        "participation_score": 25
    },
    "email2@yellowdig.com": {
        "user_id": 881,
        "board_id": 10,
        "email": "email2@yellowdig.com",
        "total_points": 106,
        "participation_score": 100
    }
}
/lms_user/:prop/:val/points

all points by user found via custom LMS user id - (NOTE: this requires custom configuration)

example request

curl -H 'apikey: $API_KEY' https://api.yellowdig.com/v1/lms_user/:prop/:val/points

example response

{
    "123124": {
        "user_id": 123124,
        "board_id": 12312873,
        "email": "email@yellowdig.com",
        "total_points": 48,
        "participation_score": 68
    },
    "123125": {
        "user_id": 123125,
        "board_id": 12312874,
        "email": "email2@yellowdig.com",
        "total_points": 49,
        "participation_score": 70
    }
}

Missing something you'd like to see in the API?
Leave us a note here or email us at: dev@yellowdig.com.