LinkLocker

Auth Code Request Endpoint (GET)

https://linklocker.co/oauth/authorize

The user authorization link should be built on this endpoint, with the following URL parameters specified in a GET request:

• client_id Required: string The client ID that you received from LinkLocker when you registered your application
• redirect_uri Required: string Must match the callback URL that you supplied during application registration. The callback URL where users will be sent after authorization. In native applications, a URL with a custom URL scheme is best.
• response_type Required: string Must be set to "code."
• scope Required: string Must be set to "readwrite," which is currently the only scope allowed, and also the default in cases where it isn't specified
• state Recommended: string This parameter can be used to pass application state back to the application after authentication; if this usage is not needed, you may supply a random string and check for it after authentication to prevent request forgery attacks.

Access Token Request Endpoint (POST)

https://linklocker.co/oauth/token

Once the user has authorized your application, the Auth Code Request will return a code parameter back to your specified redirect_uri. Use this code in a POST request sent to the /oauth/token endpoint, with the remaining parameters as follows:

• grant_type Required: string Must be set to "authorization_code"
• code Required: string The code you received in the response to your request in the previous step
• client_id Required: string The client ID that you received from LinkLocker when you registered your application
• client_secret Required: string The client secret that you received from LinkLocker when you registered your application
• redirect_uri Required: string Must match the callback URL that you supplied during application registration.

The response to this request will contain, among other things, an access_token and a refresh_token. The former is sent in the Authorization header of all of your API requests, and expires every hour for security reasons. The refresh_token can then be used to obtain a new access_token after the previous one has expired.

To use the refresh_token to obtain a new access_token, send another POST request to the https://linklocker.co/oauth/token endpoint with the following parameters:

• grant_type Required: string Must be set to "refresh_token"
• refresh_token Required: string The refresh_token that was received at the time the last access_token was obtained.

The response to the refresh_token request looks the same as the response to an access_token request, and contains new access and refresh tokens.

https://linklocker.co/api/v1/recent-links?offset=10&limit=15

Update (GET)

Pagination: No

https://linklocker.co/api/v1/update

Retrieves a timestamp set at the time of the user's last interaction with his / her data. Applicable interactions include adding, editing, or deleting a link, as well as editing the state of the "starred" and "readlater" parameters.

This timestamp can be used to keep user data synchronized between the LinkLocker servers and your application; for example, you might compare it with a local timestamp to see if the data on the server has changed since your application last posted data.

Example response:

{
  "last_updated": "2017-05-30T22:26:48Z"
}

Get All (GET)

Pagination: No

https://linklocker.co/api/v1/get-all

Returns a complete list of all the user's links. Also returns a value called count, which represents the total number of links saved to the user's account.

Note that there is no pagination on this method; use it only as a brute-force means of gathering all of the customer's data. In most cases, you should use /recent-links instead.

Example response:

{
  "count": 2, 
  "links": [
        {
         "category": "uncategorized",
         "description": "Corn pone (sometimes referred to as \"Indian pone\") is a type of cornbread made from a thick, malleable cornmeal dough (which is usually egg-less and milk-less) and cooked in a specific type of iron pan over an open fire (such as a frontiersman would use), using butter, margarine, shortening, or cooking oil.", 
         "id": "DYZoqOJbBEO48PLk" 
         "link": "https://en.wikipedia.org/wiki/Cornbread", 
         "readlater": false, 
         "starred": true, 
         "tags": [
           "food", 
           "corn"
         ], 
         "title": "Wikipedia: Corn Pone", 
         "ts": "2017-05-30 20:31"
        },  
        {
         "category": "favorites",
         "description": "Donec porta neque vel urna rhoncus placerat. Aenean neque nunc, bibendum quis suscipit quis, commodo in velit. Proin tempor rutrum urna eget blandit. Morbi scelerisque molestie ipsum quis sagittis. In dapibus velit ut urna tempor aliquet. Quisque eu dolor enim. Praesent vehicula arcu sit amet ipsum lobortis pretium.", 
         "id": 6K1WyNG5zEglBkEv, 
         "link": "http://lorem.net", 
         "readlater": false, 
         "starred": false, 
         "title": "Lorem", 
         "ts": "2017-05-20 06:55"
        }
      ], 
  "returned": 2
}

Get Recent Links (GET)

Pagination: Yes

https://linklocker.co/api/v1/recent-links

Returns a list of the user's most recently saved links. Returns 10 links by default.

Get Link by ID (GET)

Pagination: No

https://linklocker.co/api/v1/links/id/<LINK ID>

Returns a single link with the given ID.

Example Response:

{
  "links": [
    {
     "category": "uncategorized",
     "description": "Corn pone (sometimes referred to as \"Indian pone\") is a type of cornbread made from a thick, malleable cornmeal dough (which is usually egg-less and milk-less) and cooked in a specific type of iron pan over an open fire (such as a frontiersman would use), using butter, margarine, shortening, or cooking oil.", 
     "id": "DYZoqOJbBEO48PLk" 
     "link": "https://en.wikipedia.org/wiki/Cornbread", 
     "readlater": false, 
     "starred": true, 
     "tags": [
       "food", 
       "corn"
     ], 
     "title": "Wikipedia: Corn Pone", 
     "ts": "2017-05-30 20:31"
    }
  ]
}

Get Link by URL (GET)

Pagination: No

https://linklocker.co/api/v1/links/url/<URL>

Returns a single link which matches the given URL.

Get Links by Date (GET)

Pagination: Yes

https://linklocker.co/api/v1/links/date/<DATE>

Returns all links saved on the given date. Date must be formatted thusly: %Y-%m-%d (e.g. 2019-12-31).

Get Links by Tag (GET)

Pagination: Yes

https://linklocker.co/api/v1/links/tag/<TAG>

Returns links with the given tag. Don't forget that tags support spaces, which must be URL-encoded.

Get Links by Category (GET)

Pagination: Yes

https://linklocker.co/api/v1/links/category/<CATEGORY>

Returns links with the given category. Don't forget that categories support spaces, which must be URL-encoded. Uncategorized links can be retrieved with "uncategorized" as the specified category.

Get Reading List (GET)

Pagination: Yes

https://linklocker.co/api/v1/reading-list

Returns the user's Reading List (links marked to be read).

Get Starred Links (GET)

Pagination: Yes

https://linklocker.co/api/v1/starred

Returns the links the user has starred.

Get Tags (GET)

Pagination: No

https://linklocker.co/api/v1/tags

Retrives an array of all the user's tags, as well as the number of links on which each tag appears. Also returns a value called count, which represents the total number of tags in the user's account.

Each item in the array of tags, in turn, countains an individual tag, as well as instance_count (the number of links which bear the tag in question).

By default, the returned data is sorted by instance_count in descending order (meaning that the most-used tags are at the top of the list, and the least-used at the bottom). Optionally, you may supply sort-order parameters thusly:

• https://linklocker/api/v1/tags/alphabetical
• https://linklocker/api/v1/tags/reverse-alphabetical
• https://linklocker/api/v1/tags/ascending
• https://linklocker/api/v1/tags/descending

alphabetical will return a list sorted alphabetically by the name of the tag, reverse-alphabetical will return a list sorted alphabetically by the name of the tag in reverse order, ascending returns a list sorted by instance_count in ascending order, etc.

Example Response:

{
  "count": 4, 
  "tags": [
    {
     "instance_count": 4, 
     "tag": "linklocker"
    }, 
    {
     "instance_count": 3, 
     "tag": "example tag"
    }, 
    {
     "instance_count": 2, 
     "tag": "another example"
    }, 
    {
     "instance_count": 1, 
     "tag": "corn"
    }
  ]
}

Get Categories (GET)

Pagination: No

https://linklocker.co/api/v1/categories

Retrives an array of all the user's categories, as well as the number of links within each category. Also returns a value called count, which represents the total number of categories in the user's account.

Each item in the array of categories, in turn, countains:

• a list of the category's ancestors, which can be used in representing the user's categorization hierarchy within your application;
• a category's id;
• an instance_count, the number of links within the specified category;
• a category's name;
• a category's parent (also available in the ancestors list, but included separately for convenience).

Example Response:

{
  "categories": [
    {
      "ancestors": [], 
      "id": 2208, 
      "instance_count": 13, 
      "name": "example category", 
      "parent": 2205
    }, 
    {
      "ancestors": [
        2208
      ], 
      "id": 2209, 
      "instance_count": 8, 
      "name": "example subcategory", 
      "parent": 2208
    }
  ], 
  "count": 2
}

Get Category (GET)

Pagination: No

https://linklocker.co/api/v1/category/<CATEGORY>

Retrives an array of metadata pertaining to a specified category. This array contains:

• a list of the category's ancestors, which can be used in representing the user's categorization hierarchy within your application;
• the category's id;
• an instance_count, the number of links within the specified category;
• the category's name;
• the category's parent (also available in the ancestors list, but included separately for convenience).

Example Response:

{
  "category": [
    {
      "ancestors": [], 
      "id": 2195, 
      "instance_count": 3, 
      "name": "example category", 
      "parent": null
    }
  ]
}

Search (GET)

Pagination: Yes

https://linklocker.co/api/v1/search/<QUERY>

Note: To ensure that accurate results are returned, it is highly recommended that you URL-encode all input.

Returns results for supplied search term. Note that the count value represents the total number of search results found for the search term (irrespective of the number of results returned by your pagination arguments). This feature is useful for displaying to the user things like "500 results for 'LinkLocker'..." while paginating the actual displayed results.

All of the search functionality available on the site is also available here:

• To search for a full string, enclose the string in quotation marks
• To search for a tag, preface the query with "tag:," e.g. tag:python
• The "+" operator is available for AND searches; note that URL-encoded spaces must surround the "+" (e.g. search + query)
• OR searches can be performed simply by including spaces between search terms

Add a Link (POST)

Pagination: No

https://linklocker.co/api/v1/add

Example Request Body:

title=Wikipedia%3A+Corn+Pone&link=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FCornbread%23Corn_pone&description=Corn+pone+%28sometimes+referred+to+as+%22Indian+pone%22%29+is+a+type+of+cornbread+made+from+a+thick%2C+malleable+cornmeal+dough+%28which+is+usually+egg-less+and+milk-less%29+and+cooked+in+a+specific+type+of+iron+pan+over+an+open+fire+%28such+as+a+frontiersman+would+use%29%2C+using+butter%2C+margarine%2C+shortening%2C+or+cooking+oil.&tags=food%2C+corn&starred=True&readlater=True&category=food

Adds a new link to the user's account. Data must be sent via a POST request which contains (at least some of) the following parameters in its body:

• link required: UTF-8 string The URL. Maximum length is 512 characters.
• title required: UTF-8 string A title for the link, with a maximum of 256 characters. Usually this is taken from the linked page's title tag.
• description: UTF-8 string A textual description or note about the link, consisting of a maximum of 1024 characters.
• tags: UTF-8 string Must be comma-separated, can contain spaces, lowercase will be coerced. Individual tags can be any length, but the total length of the tag string must not exceed 400 characters.
• category: UTF-8 string Can contain spaces, lowercase will be coerced. The total length of the category string must not exceed 100 characters. Will create a new category by this name if one does not exist. If input is "none," the category's parent will be set to null, and it will thus be at the top level of the hierarchy.
• starred: Boolean true is starred, false (default) is not starred
• readlater: Boolean true is marked to be read later, false (default) is unmarked

Example Response:

{
  "add": "Success!"
}

Edit Link (PUT)

Pagination: No

https://linklocker.co/api/v1/edit

Edits an existing link given that link's (required) ID via a PUT request, with any and/or all of the following parameters given in the request body:

• id required: UTF-8 string The link's ID. Always 16 characters.
• edit_link: UTF-8 string The URL. Maximum length is 512 characters.
• edit_title: UTF-8 string A title for the link, with a maximum of 140 characters. Usually this is taken from the linked page's title tag.
• edit_description: UTF-8 string A textual description or note about the link, consisting of a maximum of 1024 characters.
• edit_tags: UTF-8 string Must be comma-separated, can contain spaces, lowercase will be coerced. Individual tags can be any length, bu the total length of the tag string must not exceed 400 characters.
• edit_category: UTF-8 string Can contain spaces, lowercase will be coerced. The total length of the category string must not exceed 100 characters. Will create a new category by this name if one does not exist. If input is "uncategorized," the link will be marked as such. Integer input will be coerced to a string.
• edit_starred: Boolean true is starred, false (default) is not starred.
• edit_readlater: Boolean true is marked to be read later, false (default) is unmarked.

Example Response:

{
  "edit": "Success!"
}

Delete Link (DELETE)

Pagination: No

https://linklocker.co/api/v1/delete/<LINK ID>

Deletes the link with the given ID.

Example Response:

{
  "delete_link_6K1WyNG5zEglBkEv": "Deleted!"
}

Create Category (POST)

Pagination: No

https://linklocker.co/api/v1/create-category

Example Request Body:

category=example&parent=none

Adds a new category to the user's account and returns the new category's ID. Data must be sent via a POST request which contains the following parameters in its body.

• category required: UTF-8 string The category's name. Maximum length is 100 characters.
• parent UTF-8 string Optionally, you can specify the new category's parent (the new category will be nested within the parent, becoming its subcategory). If the specified value is "none," the category's parent will be set to null, and it will thus be at the top level of the hierarchy.

Example Response:

{
  "id": "2219"
}

Edit Category (PUT)

Pagination: No

https://linklocker.co/api/v1/category/edit

Example Request Body:

id=2219&name=example&parent=favorites

Edits an existing category given that category's (required) ID via a PUT request.

• id required: Integer The category's ID.
• name: UTF-8 string The category's name. Maximum length is 100 characters. If none is specified, no change will be made.
• parent UTF-8 string OR Integer Specify a new parent for the category if desired. You may specify either the name of an existing parent category or the parent's id value. If no value is specified, no change will be made. If the specified value is "none," the category's parent will be set to null, and it will thus be at the top level of the hierarchy.

Example Response:

{
  "id": 2219, 
  "name": "example", 
  "parent": 1596
}

Delete Category (DELETE)

Pagination: No

https://linklocker.co/api/v1/category/delete/<CATEGORY NAME>

Deletes the category named in the URL. All links with this category will be changed to "UNCATEGORIZED." Any child categories will be adopted by the deleted category's parent, if any. Don't forget that categories support spaces, which must be URL-encoded.

Example Response:

{
  "delete_category_example": "Deleted!"
}