API

Headers

The API supports the CBOR serialization format. To use this format, set the Accept header to application/cbor. The API will return the response in CBOR format.

Authentication

To use the API, please create an API key in your account settings. This key will be used to authenticate your requests. You must select the appropriate type of API key, using the following reference:

Type	Description
Long Lived	This key can be used to access the modern API
Pinboard	This key can be used to access the legacy Pinboard compatibility API
RSS	This key can be used to access private items in your RSS feed, by appending ?key=<key> to the URL
Fever	This key can be used to access the legacy Fever compatibility API
Google Reader	This key can be used to access the legacy Google Reader compatibility API

Rules

When developing applications for the API, please use the following rules:

• Caching: Please cache responses from the API
• Identification: Please identify your application in the User-Agent header. Requests made without a User-Agent header will fail
• Reasonable Use: Please do not attempt to overwhelm the API with requests
• /user Endpoints: Do not attempt to modify a user's settings, create sessions, or perform any other account related actions on their behalf. Circumventing anti-bot measures is also prohibited. This is for user safety.

Concepts

Definitions

• entity represents a foreign resource that has been saved to Pinefore in some way. An entity is basically a hashmap of id:url pairs.
• pins extend entities with user specific metadata, like the description the user wrote for it.
• objects are the most general term for resources in Pinefore. They can be entities, pins, or any other resource.
• tags are used to categorize objects.

Tag Networks

When an API returns a tag network, the first layer is the tag's peers. If I request information on the tag operating-systems, one peer might be linux. There is not currently more depth.

Compatibility Layers

For all compatibility layers:

• Error formats, headers and status codes may not always be correct
• In many cases, APIs may return more than is in the original docs. This is called a superset. The values of defined fields shouldn't change though. Only new ones that are added.
• In some limited cases, the generated token to use with APIs will be different than what is defined by the spec. The expectation is that clients do not run integrity checks on the token.
• API limits may be different than what is documented.
• If you encounter issues arising from these or any other differences with the original APIs, reach out to me.