The Path API allows a Path user to securely grant your application access to their account and act on their behalf. This includes access to the user's profile, friend list, and the ability to post moments to their Path.

To use the API, you must first obtain a key for your application. Click here to apply.

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

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
200OKOk
201CREATEDResource created
202ACCEPTEDAccepted for processing

Errors

Code Type Reason
400BAD_ARGInvalid or bad argument
401UNAUTHORIZEDRequest is unauthorized
403ACCESS_DENIEDAccess to resource denied
404NOT_FOUNDResource not found
429RATE_LIMIT_EXCEEDEDRate limit exceeeded
500SERVER_ERRORInternal server error

GET /user/:id

Required Permissions

  • authorization
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": "",
        "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
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 StringOptional. See: http://www.iana.org/time-zones
created FloatOptional. UNIX time epoch (UTC). The time the moment was created.
private BooleanOptional. If true the moment is visible to only the creator.
ic BooleanOptional. If true the moment is visible to inner-circle friends.
captured FloatOptional. UNIX time epoch (UTC). The time the photo was captured.
filter StringOptional. The name of the filter that was applied to the photo.
caption StringOptional. Displayed as the first comment.
tags TagsOptional. Array of tag objects. Supported types: user, place, location.
links LinksOptional. Object of links for deeplinking to this resource.

From Binary

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

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 StringOptional. See: http://www.iana.org/time-zones
created FloatOptional. UNIX time epoch (UTC). The time the moment was created.
private BooleanOptional. If true the moment is visible to only the creator.
ic BooleanOptional. If true the moment is visible to inner-circle friends.
captured FloatOptional. UNIX time epoch (UTC). The time the video was captured.
filter StringOptional. The name of the filter that was applied to the video.
caption StringOptional. Displayed as the first comment.
tags TagsOptional. Array of tag objects. Supported types: user, place, location.
links LinksOptional. Object of links for deeplinking to this resource.

From Binary

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

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 StringRequired. The thought text.
timezone StringOptional. See: http://www.iana.org/time-zones
created FloatOptional. UNIX time epoch (UTC). The time the moment was created.
private BooleanOptional. If true the moment is visible to only the creator.
ic BooleanOptional. If true the moment is visible to inner-circle friends.
tags TagsOptional. Array of tag objects. Supported types: user, place, location.
links LinksOptional. Object of links for deeplinking to this resource.
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 StringRequired. The type of place represented by source_id. Currently only Foursquare is supported.
source_id StringRequired. Unique identifier representing the place.
timezone StringOptional. See: http://www.iana.org/time-zones
created FloatOptional. UNIX time epoch (UTC). The time the moment was created.
private BooleanOptional. If true the moment is visible to only the creator.
ic BooleanOptional. If true the moment is visible to inner-circle friends.
caption StringOptional. Displayed as the first comment.
tags TagsOptional. Array of tag objects. Supported types: user, location.
links LinksOptional. Object of links for deeplinking to this resource.
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
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