Path - API Documentation

Authentication

The authentication layer implements OAuth 2.0, an open standard suitable for 3-legged authorization. OAuth allows users to authorize your application without disclosing their Path username and password.

Note: We assume that you obtained client credentials which include a client_id and client_secret. You should have also chosen a redirect_url for your app.

To begin the auth process, send the user to the following URL:
https://partner.path.com/oauth2/authenticate?response_type=code&client_id=YOUR_CLIENT_ID

When the Path user grants permission for your client application to act on her behalf, she will be redirected to your client application's redirect_url with a code that can be exchanged for an access token.

The code should be exchanged for an access token using /oauth2/access_token. At this point you will be issued a permanent access token that your application can use to authenticate as the Path user.

POST /oauth2/access_token

Request
Response
cURL

POST /oauth2/access_token HTTP/1.1
Host: partner.path.com
Content-Type: application/x-www-form-urlencoded
Content-Length: <LENGTH>

grant_type=authorization_code&client_id=CLIENT&client_secret=SECRET&code=CODE

HTTP/1.1 201 CREATED
Content-Type: application/json
Content-Length: <LENGTH>

{
    "code": 201,
    "type": "CREATED"
    "reason": "Created",
    "access_token": <ACCESS_TOKEN>,
    "user_id": <USER_ID>,
}

curl -X POST \
     -F 'grant_type=authorization_code' \
     -F 'client_id=CLIENT_ID' \
     -F 'client_secret=CLIENT_SECRET' \
     -F 'code=CODE' \
     https://partner.path.com/oauth2/access_token

Permissions

Every client application is issued a set of permissions that a Path user will be asked to grant. The following permissions are currently:

email_read	Read a Path user's email address.
moments_write	Create a photo or video moment in the user's Path feed.
friends_read	View a Path user's friend list.

Status Codes

Success

Code	Type	Reason
200	OK	Ok
201	CREATED	Resource created
202	ACCEPTED	Accepted for processing

Errors

Code	Type	Reason
400	BAD_ARG	Invalid or bad argument
401	UNAUTHORIZED	Request is unauthorized
403	ACCESS_DENIED	Access to resource denied
404	NOT_FOUND	Resource not found
429	RATE_LIMIT_EXCEEDED	Rate limit exceeeded
500	SERVER_ERROR	Internal server error

GET /user/:id

Required Permissions

authorization

Request
Response
cURL

GET /1/user/self HTTP/1.1
Host: partner.path.com
Authorization: Bearer <ACCESS_TOKEN>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <LENGTH>

{
    "reason": "Ok",
    "code": 200,
    "type": "OK",
    "user": {
        "source": "path",
        "type": "user",
        "id": "<USER_ID>",
        "name": "Dwigt Schrute",
        "photo": {
            "small": {
                "url": "https://pathakacdn-a.akamaihd.net/profile_photos/f8dee47038fb5f17281ab8b2ff3a5234a3f19db8/processed_80x80.jpg",
                "width": 80,
                "height": 80
            },
            "medium": {
                "url": "https://pathakacdn-a.akamaihd.net/profile_photos/f8dee47038fb5f17281ab8b2ff3a5234a3f19db8/processed_160x160.jpg",
                "width": 160,
                "height": 160
            },
            "original": {
                "url": "https://pathakacdn-a.akamaihd.net/profile_photos/f8dee47038fb5f17281ab8b2ff3a5234a3f19db8/original.jpg",
                "width": 1333,
                "height": 1333
            }
        }
    }
}

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    https://partner.path.com/1/user/self

GET /user/:id/friends

Required Permissions

friends_read

Request
Response
cURL

GET /1/user/self/friends HTTP/1.1
Host: partner.path.com
Authorization: Bearer <ACCESS_TOKEN>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <LENGTH>

{
    "friends": [
        {
            "source": "path",
            "type": "user",
            "id": "<USER_ID>",
            "name": "Dwigt Schrute",
            "photo": {
                "small": {
                    "url": "https://pathakacdn-a.akamaihd.net/profile_photos/f8dee47038fb5f17281ab8b2ff3a5234a3f19db8/processed_80x80.jpg",
                    "width": 80,
                    "height": 80
                },
                "medium": {
                    "url": "https://pathakacdn-a.akamaihd.net/profile_photos/f8dee47038fb5f17281ab8b2ff3a5234a3f19db8/processed_160x160.jpg",
                    "width": 160,
                    "height": 160
                },
                "original": {
                    "url": "https://pathakacdn-a.akamaihd.net/profile_photos/f8dee47038fb5f17281ab8b2ff3a5234a3f19db8/original.jpg",
                    "width": 1333,
                    "height": 1333
                }
            }
        }
    ],
    "reason": "Ok",
    "code": 200,
    "type": "OK"
}

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    https://partner.path.com/1/user/self/friends

Moment Tags

A moment can be tagged with associated people and places. A "tag object" is a JSON object containing a required type key. All other keys vary based on the tag type.

Note: Not all moments use all tag types. See moment specific documentation to confirm a moment's supported tag objects.

Available Tags

Type	Fields	Description
user	`sourceid`	A user. The `source` field determines the network that the user originates from. The following sources are supported: `path`, `facebook`
place	`sourceid`	A place. The `source` field determines the network that the place originates from. The following sources are supported: `foursquare`
location	`latitudelongitudevelocityheadingaccuracyelevationelevation_accuracy`	A geographic location. `latitude` and `longitude` are required. All other fields optional.

Moment Links

Your moment may have an associated link with your application. Use the link property to define this association.

Recognized Link Types

Type	Description
web	Resource location on the web.
ios	A custom URL scheme can be used to deeplink directly into your iOS application.
android	A custom URL scheme can be used to deeplink directly into your Android application.

POST /1/moment/photo

Publish a photo to a user's moments feed. The photo data may be transmitted in two ways: by sending a binary or by providing a source URL.

Required Permissions

authorization
moments_write

Parameters

Name	Type	Description
timezone	String	Optional. See: http://www.iana.org/time-zones
created	Float	Optional. UNIX time epoch (UTC). The time the moment was created.
private	Boolean	Optional. If `true` the moment is visible to only the creator.
ic	Boolean	Optional. If `true` the moment is visible to inner-circle friends.
captured	Float	Optional. UNIX time epoch (UTC). The time the photo was captured.
filter	String	Optional. The name of the filter that was applied to the photo.
caption	String	Optional. Displayed as the first comment.
tags	Tags	Optional. Array of tag objects. Supported types: user, place, location.
links	Links	Optional. Object of links for deeplinking to this resource.

From Binary

Request
Response
cURL

POST /1/moment/photo HTTP/1.1
Host: partner.path.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: multipart/form-data; boundary="mymultipartboundary"
Content-Length: <LENGTH>

--mymultipartboundary
Content-Disposition: form-data; name="image"; filename="name-of-file.jpg"
Content-Type: image/jpeg;

<BINARY_DATA>
--mymultipartboundary
Content-Disposition: form-data; name="data"
Content-Type: application/json

{"caption": "I like cheese!"}
--mymultipartboundary--

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: <LENGTH>

{
    "reason": "Accepted for processing",
    "code": 202,
    "type": "ACCEPTED",
    "moment": {
        "type": "photo",
        "id": "4a1e2c581caf49feb68fe673435a09ea"
    }
}

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -F "image=@path/to/photo.jpg" \
     -F 'data={"caption": "I like cheese!"}' \
     https://partner.path.com/1/moment/photo

From URL

Request
Response
cURL

POST /1/moment/photo HTTP/1.1
Host: partner.path.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Content-Length: <LENGTH>

{
    "source_url": "http://url/to/photo.jpg",
    "caption": "I like cheese!"
}

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: <LENGTH>

{
    "reason": "Accepted for processing",
    "code": 202,
    "type": "ACCEPTED",
    "moment": {
        "type": "photo",
        "id": "<MOMENT_ID>"
    }
}

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d '{"source_url": "http://url/to/photo.jpg", "caption": "I like cheese!"}' \
     https://partner.path.com/1/moment/photo

POST /moment/video

Publish a video to a user's moments feed. The video data may be transmitted in two ways: by sending a binary or by providing a source URL.

Required Permissions

authorization
moments_write

Parameters

Name	Type	Description
timezone	String	Optional. See: http://www.iana.org/time-zones
created	Float	Optional. UNIX time epoch (UTC). The time the moment was created.
private	Boolean	Optional. If `true` the moment is visible to only the creator.
ic	Boolean	Optional. If `true` the moment is visible to inner-circle friends.
captured	Float	Optional. UNIX time epoch (UTC). The time the video was captured.
filter	String	Optional. The name of the filter that was applied to the video.
caption	String	Optional. Displayed as the first comment.
tags	Tags	Optional. Array of tag objects. Supported types: user, place, location.
links	Links	Optional. Object of links for deeplinking to this resource.

From Binary

Request
Response
cURL

POST /1/moment/video HTTP/1.1
Host: partner.path.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: multipart/form-data; boundary="mymultipartboundary"
Content-Length: <LENGTH>

--mymultipartboundary
Content-Disposition: form-data; name="video"; filename="name-of-file.mp4"
Content-Type: video/mp4;

<BINARY_DATA>
--mymultipartboundary
Content-Disposition: form-data; name="data"
Content-Type: application/json

{"caption": "I like cheese!"}
--mymultipartboundary--

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: <LENGTH>

{
    "reason": "Accepted for processing",
    "code": 202,
    "type": "ACCEPTED",
    "moment": {
        "type": "video",
        "id": "<MOMENT_ID>"
    }
}

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -F "video=@path/to/video.mp4" \
     -F 'data={"caption": "I like cheese!"}' \
     https://partner.path.com/1/moment/video

From URL

Request
Response
cURL

POST /1/moment/video HTTP/1.1
Host: partner.path.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Content-Length: <LENGTH>

{
    "source_url": "http://url/to/video.mp4",
    "caption": "I like cheese!"
}

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: <LENGTH>

{
    "reason": "Accepted for processing",
    "code": 202,
    "type": "ACCEPTED",
    "moment": {
        "type": "video",
        "id": "<MOMENT_ID>"
    }
}

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d '{"source_url": "http://url/to/video.mp4"}' \
     https://partner.path.com/1/moment/video

POST /moment/thought

Publish a thought moment to a user's feed.

Required Permissions

authorization
moments_write

Parameters

Name	Type	Description
thought	String	Required. The thought text.
timezone	String	Optional. See: http://www.iana.org/time-zones
created	Float	Optional. UNIX time epoch (UTC). The time the moment was created.
private	Boolean	Optional. If `true` the moment is visible to only the creator.
ic	Boolean	Optional. If `true` the moment is visible to inner-circle friends.
tags	Tags	Optional. Array of tag objects. Supported types: user, place, location.
links	Links	Optional. Object of links for deeplinking to this resource.

Request
Response
cURL

POST /1/moment/thought HTTP/1.1
Host: partner.path.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Content-Length: <LENGTH>

{
    "thought": "I like cheese!"
}

HTTP/1.1 201 CREATED
Content-Type: application/json
Content-Length: <LENGTH>

{
    "reason": "Created",
    "code": 201,
    "type": "CREATED",
    "moment": {
        "type": "thought",
        "id": "<MOMENT_ID>"
    }
}

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d '{"thought": "I like cheese!"} \
     https://partner.path.com/1/moment/thought

POST /moment/place

Publish a place moment to a user's feed.

Required Permissions

authorization
moments_write

Parameters

Name	Type	Description
source	String	Required. The type of place represented by `source_id`. Currently only Foursquare is supported.
source_id	String	Required. Unique identifier representing the place.
timezone	String	Optional. See: http://www.iana.org/time-zones
created	Float	Optional. UNIX time epoch (UTC). The time the moment was created.
private	Boolean	Optional. If `true` the moment is visible to only the creator.
ic	Boolean	Optional. If `true` the moment is visible to inner-circle friends.
caption	String	Optional. Displayed as the first comment.
tags	Tags	Optional. Array of tag objects. Supported types: user, location.
links	Links	Optional. Object of links for deeplinking to this resource.

Request
Response
cURL

POST /1/moment/place HTTP/1.1
Host: partner.path.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Content-Length: <LENGTH>

{
    "source": "foursquare",
    "source_id": "<PLACE_ID>",
    "caption": "I like cheese!"
}

HTTP/1.1 201 CREATED
Content-Type: application/json
Content-Length: <LENGTH>

{
    "reason": "Created",
    "code": 201,
    "type": "CREATED",
    "moment": {
        "type": "place",
        "id": "<MOMENT_ID>"
    }
}

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d '{"source": "foursquare", "source_id": "<PLACE_ID>"} \
     https://partner.path.com/1/moment/place

API Health

Provides a runtime system status check.

Required Permissions

None

Request
Response
cURL

GET /1/health HTTP/1.1
Host: partner.path.com

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <LENGTH>

{
    "health": "ok",
    "reason": "Ok",
    "code": 200,
    "type": "OK"
}

curl https://partner.path.com/1/health