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.

If you are interested in connecting your app to Path or you have any inquiry, please contact us at api@path.com.


Since we've decided to limit the number of partners we can work with for the time being, sometimes applications would not be responded. However, please stay tuned as we may look to expand our API program in the future.

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_readRead a Path user's email address.
moments_writeCreate a photo or video moment in the user's Path feed.
friends_readView a Path user's friend list.

Status Codes

Success

CodeTypeReason
200OKOk
201CREATEDResource created
202ACCEPTEDAccepted for processing

Errors

CodeTypeReason
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": "<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

TypeFieldsDescription
usersourceidA user. The source field determines the network that the user originates from. The following sources are supported: path, facebook
placesourceidA place. The source field determines the network that the place originates from. The following sources are supported: foursquare
locationlatitudelongitudevelocityheadingaccuracyelevationelevation_accuracyA 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

TypeDescription
webResource location on the web.
iosA custom URL scheme can be used to deeplink directly into your iOS application.
androidA 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

NameTypeDescription
timezoneStringOptional. See: http://www.iana.org/time-zones
createdFloatOptional. UNIX time epoch (UTC). The time the moment was created.
privateBooleanOptional. If true the moment is visible to only the creator.
icBooleanOptional. If true the moment is visible to inner-circle friends.
capturedFloatOptional. UNIX time epoch (UTC). The time the photo was captured.
filterStringOptional. The name of the filter that was applied to the photo.
captionStringOptional. Displayed as the first comment.
tagsTagsOptional. Array of tag objects. Supported types: user, place, location.
linksLinksOptional. 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

NameTypeDescription
timezoneStringOptional. See: http://www.iana.org/time-zones
createdFloatOptional. UNIX time epoch (UTC). The time the moment was created.
privateBooleanOptional. If true the moment is visible to only the creator.
icBooleanOptional. If true the moment is visible to inner-circle friends.
capturedFloatOptional. UNIX time epoch (UTC). The time the video was captured.
filterStringOptional. The name of the filter that was applied to the video.
captionStringOptional. Displayed as the first comment.
tagsTagsOptional. Array of tag objects. Supported types: user, place, location.
linksLinksOptional. 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

NameTypeDescription
thoughtStringRequired. The thought text.
timezoneStringOptional. See: http://www.iana.org/time-zones
createdFloatOptional. UNIX time epoch (UTC). The time the moment was created.
privateBooleanOptional. If true the moment is visible to only the creator.
icBooleanOptional. If true the moment is visible to inner-circle friends.
tagsTagsOptional. Array of tag objects. Supported types: user, place, location.
linksLinksOptional. 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

NameTypeDescription
sourceStringRequired. The type of place represented by source_id. Currently only Foursquare is supported.
source_idStringRequired. Unique identifier representing the place.
timezoneStringOptional. See: http://www.iana.org/time-zones
createdFloatOptional. UNIX time epoch (UTC). The time the moment was created.
privateBooleanOptional. If true the moment is visible to only the creator.
icBooleanOptional. If true the moment is visible to inner-circle friends.
captionStringOptional. Displayed as the first comment.
tagsTagsOptional. Array of tag objects. Supported types: user, location.
linksLinksOptional. 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