You are not logged in. Sign up or Log in to gain access to an API key.
Sign Up
Log In

Introduction

This is our API. If you are an engineer with any talent or skill, you will know exactly how to use it and you will be capable of making something fantastic and delightful with it. If you have any questions you are probably an idiot. However, if you must, please email api@jotly.co with a very polite and forthcoming emailing outlining all of your wants and desires. In the meantime, please use this API to make something worthwhile and world-changing, like Cat vs Dog.

Getting Started

To make requests to the API you either need a client_key (to make logged out requests) or an access_token (to make all requests). To get a client_key you can log in above and then press the button to get a key.

All endpoints are only accessible via https and are located at jot-ly.appspot.com. For instance: you can grab the most recent Jots by accessing the following URL with your client_key (replace CLIENT-KEY with your own): 

https://jot-ly.appspot.com/api/v1/feed?client_key=CLIENT-KEY

If you have an access_token to use for each of your users then use it instead of client_key. We limit per token/key, so using the access_token for each user gives you more requests.

Image Assets

Here is a zip of all of the grade icons as well as a Jotly logo if you want it for your client.

jotly_api_graphics.zip

Authenticating

Jotly's API uses client login to authenticate users (see the login API endpoint below for details). You can hit the log in and sign up endpoints with your client_key to authenticate users. We might eventually move to OAuth for authentication, but we didn't feel like creating an OAuth login page. All requests to the api must be made over SSL (https:// not http://)

For the most part, Jotly's API requires the use of a client_key. A client_key allows for your server, script, or client program to make requests by identifying yourself as associated with a specific app. Authenticated requests require an access_token. Authenticated requests are requests that are made on behalf of a single user. These tokens should be stored securely, and you should expect that they may expire at any time in the future. For instance: you can get the authenticated user's Jots by accessing the following URL with your access_token. 

https://jot-ly.appspot.com/api/v1/feed/user/self?access_token=ACCESS-TOKEN

Image URLS and dates

Image URLs are passed back for both Jots and users as "image_url". You can pass a "w" parameter to the image URL to specify what width of the image you want returned. All images are cropped to squares. Ex: http://www.jotly.co/jotimage/75804?w=500.

All dates are returned as "date" and are unix timestamps.

API Endpoints

Here is the list of all of the possible requests you can make with the Jotly API. All POST requests other than login or signup require an access_token parameter. The access_token can be used in replace of the client_key if you have it, else any GET request can be used with just a client_key parameter.

Responses are JSON objects. The main response data is returned under the "data" key. If there is an error with the request an HTTP error response code will be returned as well as JSON with the key "error" and value being the error type.

POST /login

Log in on behalf of a user with their email and password.

Parameters

emailA valid email address
passwordPassword associated with the email address

Example

https://jot-ly.appspot.com/api/v1/login
{
    "access_token": "VXxgMFyxkGm6kQBESf4N2rXqJ2aHx5",
    "data": {
        "image_url": "http://www.jotly.co/userimage/56002",
        "id": "56002",
        "name": "Phil Mills"
    },
    "user_id": "56002"
}
POST /signup

Sign up a new Jotly user. Sign up through the Jotly API is turned off by default for all clients. If you want to be able to let users sign up through your client send an email to api@jotly.co with your client_key and why you want sign up abilities.

Parameters

nameDisplay name for the new user
emailA valid email address
passwordPassword for the new user
avatarImage for the user's avatar

Example

https://jot-ly.appspot.com/api/v1/signup
{
    "access_token": "e7Gy9vHuybUhPf95B56WJRJg7BwxLH",
    "data": {
        "image_url": "http://www.jotly.co/userimage/58003",
        "id": "58003",
        "name": "Alex"
    },
    "user_id": "58003"
}
GET /feed/{feed-type}

Get a list of Jots. {feed-type} is either of these: recent|nearby|mostliked|mostcommented|user|mylikes|mycomments

The feed and search API endpoints will return a "cursor" value to be used when paginating. To paginate you pass the cursor on subsequent requests as a parameter with the limit of how many results you want.

Parameters

access_tokenNeeded for user|mylikes|mycomments feed types. (optional)
limitNumber of Jots to return. (default=10)
cursorPagination cursor if you are requesting any page other than the first. (optional)
geocodeUsed only for nearby feed. Value is "{latitude},{longitude}" (optional)

Example

https://jot-ly.appspot.com/api/v1/feed/recent
{

    "cursor": "E-ABAOsB8gEEZGF0ZfoBCQi_t9POptWtAuwBggIXaghzfvpvdC3seXILCxIDSm90GNCkCQwU",
    "data": [
        {
            "user": {
                "image_url": "http://www.jotly.co/userimage/56002",
                "id": "56002",
                "name": "Phil Mills"
            },
            "rating": 15,
            "description": "#badass",
            "title": "Tony The Bartender",
            "grade": "A+",
            "source": null,
            "views": 19,
            "tags": [
                "#badass"
            ],
            "longitude": -73.955734,
            "date": "1324014605",
            "image_url": "http://www.jotly.co/jotimage/74273",
            "likes": 1,
            "latitude": 40.720274,
            "id": "74273",
            "comments": 2
        },
        ...
    ]
}
GET /feed/user/{user-id}

Get a user's list of Jots. {user-id} is either a user id or "self".

The feed and search API endpoints will return a "cursor" value to be used when paginating. To paginate you pass the cursor on subsequent requests as a parameter with the limit of how many results you want.

Parameters

access_tokenNeeded only if you are using the "self" user id value. (optional)
limitNumber of Jots to return. (default=10)
cursorPagination cursor if you are requesting any page other than the first. (optional)

Example

https://jot-ly.appspot.com/api/v1/feed/user/18403
{
    "cursor": "E-ABAOsB8gEEZGF0ZfoBCQiB3IrGkbetAuwBggIXaghzfmpvdC1seXILCxIDSm90GMrTBgwU",
    "data": [
        {
            "user": {
                "image_url": "http://www.jotly.co/userimage/56002",
                "id": "56002",
                "name": "Phil Mills"
            },
            "rating": 3,
            "description": "#freezingmybaguettesoff",
            "title": "The \"feels Like Temperature\" -7!",
            "grade": "F+",
            "source": "iphone",
            "views": 8,
            "tags": [
                "#freezingmybaguettesoff"
            ],
            "longitude": 0,
            "date": "1326660706",
            "image_url": "http://www.jotly.co/jotimage/150124",
            "likes": 0,
            "latitude": 0,
            "id": "150124",
            "comments": 0
        },
        ...
    ]
}
GET /search

Search Jots. Returns a list of matching Jots.

The feed and search API endpoints will return a "cursor" value to be used when paginating. To paginate you pass the cursor on subsequent requests as a parameter with the limit of how many results you want.

Parameters

qThe search query.
limitNumber of Jots to return. (default=10)
cursorPagination cursor if you are requesting any page other than the first. (optional)

Example

https://jot-ly.appspot.com/api/v1/search?q=dog
{
    "cursor": "E-ABAOsB8gEEZGF0ZfoBCQi2_J-j3q2sAuwBggIXaghzfmpvdC1seXILCxIDSm90GL2UAQwU",
    "data": [
        {
            "user": {
                "image_url": "http://www.jotly.co/userimage/58003",
                "id": "58003",
                "name": "Alex"
            },
            "rating": 15,
            "description": "",
            "title": "Dog Sitting Like Human",
            "grade": "A+",
            "source": "iphone",
            "views": 23,
            "tags": [ ],
            "longitude": -73.989742,
            "date": "1325359100",
            "image_url": "http://www.jotly.co/jotimage/104059",
            "likes": 4,
            "latitude": 40.734209,
            "id": "104059",
            "comments": 0
        },
        ...
    ]
}
GET /leaderboard

Get the Jotly leaderboard.

Parameters

limitNumber of leaderboard users to return. (default=100, max=100)

Example

https://jot-ly.appspot.com/api/v1/leaderboard
{
    "data": [
        {
            "views": 2464,
            "image_url": null,
            "id": "60031",
            "rank": 1,
            "name": "amazingly average"
        },
        {
            "views": 2268,
            "image_url": "http://www.jotly.co/userimage/9003",
            "id": "9003",
            "rank": 2,
            "name": "Dulce"
        },
        {
            "views": 1837,
            "image_url": "http://www.jotly.co/userimage/61069",
            "id": "61069",
            "rank": 3,
            "name": "King Craig"
        },
        ...
    ]
}
GET /user/{user-id}

Get info for a single Jotly user.

Parameters

access_tokenNeeded only if you are using the "self" user id value. (optional)

Example

https://jot-ly.appspot.com/api/v1/user/56002
{
    "data": {
        "image_url": "http://www.jotly.co/userimage/56002",
        "id": "56002",
        "name": "Phil Mills"
    }
}
GET /jot/{jot-id}

Get info for a single Jot.

Example

https://jot-ly.appspot.com/api/v1/jot/75804
{
    "data": {
        "user": {
            "image_url": "http://www.jotly.co/userimage/56002",
            "id": "56002",
            "name": "Phil Mills"
        },
        "rating": 15,
        "description": "A la Gigi ",
        "title": "Red Pants",
        "grade": "A+",
        "source": null,
        "views": 28,
        "tags": [ ],
        "longitude": -74.003519,
        "date": "1325145319",
        "image_url": "http://www.jotly.co/jotimage/75804",
        "likes": 4,
        "latitude": 40.719019,
        "id": "75804",
        "comments": 2
    }
}
GET /jot/{jot-id}/comments

Get list of comments on a Jot.

Example

https://jot-ly.appspot.com/api/v1/jot/75804/comments
{
    "data": [
        {
            "comment": "So red.",
            "date": "1325145366",
            "id": "91244",
            "user": {
                "image_url": null,
                "id": "94016",
                "name": "Somat"
            }
        },
        {
            "comment": "Red like sex",
            "date": "1325145414",
            "id": "75805",
            "user": {
                "image_url": "http://www.jotly.co/userimage/56002",
                "id": "56002",
                "name": "Phil Mills"
            }
        },
        ...
    ]
}
GET /jot/{jot-id}/likes

Get list of likes for a Jot.

Example

https://jot-ly.appspot.com/api/v1/jot/75804/likes
{
    "data": [
        {
            "date": "1325145339",
            "user": {
                "image_url": "http://www.jotly.co/userimage/56002",
                "id": "56002",
                "name": "Phil Mills"
            },
            "key": "u56002c75804"
        },
        {
            "date": "1325145342",
            "user": {
                "image_url": null,
                "id": "92156",
                "name": "Swifty"
            },
            "key": "u92156c75804"
        },
        ...
    ]
}
POST /jot

Create a new Jot.

To be able to share to Facebook and Twitter, the user must already be connected to those services through Jotly. We will eventually add a way for your client to connect the user to those Services.

Parameters

access_tokenA valid access token.
titleTitle of the Jot.
descriptionDescription of the Jot. (optional)
ratingRating has to be between 1 and 15. (ex: 1=F-, 15=A+)
picturePicture of the Jot.
geocodeWhere the Jot happened. Value is "{latitude},{longitude}" (optional)
facebookSet value to "1" if you want to post to Facebook. (optional)
twitterSet value to "1" if you want to post to Twitter. (optional)

Example

https://jot-ly.appspot.com/api/v1/jot
{
    "data": {
        "rating": 14,
        "description": "#api",
        "title": "About to Unleash Hell",
        "grade": "A",
        "source": null,
        "views": 0,
        "tags": [
            "#api"
        ],
        "longitude": "",
        "date": "1326753650",
        "image_url": "http://www.jotly.co/jotimage/151162",
        "likes": 0,
        "latitude": "",
        "id": "151162",
        "comments": 0
    },
    "jot_id": "151162"
}
POST /deletejot

Delete a Jot. In order to delete, the requested Jot must be owned by the authenticated user. If no error comes back then Jot was deleted successfully.

Parameters

access_tokenA valid access token.
jot_idThe id of the Jot.

Example

https://jot-ly.appspot.com/api/v1/deletejot
{
    "data": null
}
POST /jot/{jot-id}/comment

Comment on a Jot.

Parameters

access_tokenA valid access token.
textThe comment text.

Example

https://jot-ly.appspot.com/api/v1/jot/150006/comment
{
    "data": {
        "comment": "Find it!",
        "date": "1325908080",
        "id": "149003",
        "user": {
            "image_url": "http://www.jotly.co/userimage/58003",
            "id": "58003",
            "name": "Alex"
        }
}
POST /jot/{jot-id}/like

Like a Jot.

Parameters

access_tokenA valid access token.

Example

https://jot-ly.appspot.com/api/v1/jot/75804/like
{
    "data": {
        "date": "1326466226",
        "user": {
            "image_url": "http://www.jotly.co/userimage/56002",
            "id": "56002",
            "name": "Phil Mills"
        },
        "key": "u56002c152092"
    }
}
POST /edituser

Edit a user's info. User must be the authenticated user.

Parameters

access_tokenA valid access token.
nameThe user's new display name.
avatarThe user's new avatar image.

Example

https://jot-ly.appspot.com/api/v1/edituser
{
    "data": {
        "image_url": "http://www.jotly.co/userimage/56002",
        "id": "56002",
        "name": "Phil Mills"
    }
}
Built by Firespotter Labs. All rights reserved.