The API

Cowpin implements Pinboard's v1 API, so scripts, apps, and integrations built for Pinboard work against Cowpin with one change: the base URL.

Pinboard: https://api.pinboard.in/v1/
Cowpin: https://www.cowpin.com/api/v1/

Authentication

Every request needs an auth_token in Pinboard's username:TOKEN format. Create a token in Settings → API in Cowpin, then append it to each call:

https://www.cowpin.com/api/v1/posts/all?auth_token=yourname:XXXXXXXXXXXX

Responses are XML by default (as on Pinboard). Add format=json for JSON:

https://www.cowpin.com/api/v1/posts/recent?auth_token=yourname:XXXX&format=json

Endpoints

All endpoints are GET, matching Pinboard.

Posts

Endpoint	What it does	Key parameters
`/posts/add`	Save a bookmark	`url`, `description` (title), `extended` (notes), `tags`, `dt`, `replace` (yes/no), `shared` (yes/no), `toread` (yes/no)
`/posts/delete`	Delete a bookmark	`url`
`/posts/get`	Get bookmarks for a date / URL / tag	`url`, `tag`, `dt`
`/posts/recent`	Most recent bookmarks	`tag`, `count`
`/posts/all`	Every bookmark	`tag` (rate-limited — see below)
`/posts/update`	Time of the last change	—

Parameter notes (same semantics as Pinboard):

shared=yes|no maps to public/private. Cowpin defaults new posts to private unless shared=yes.
toread=yes|no sets the read-later flag.
tags is a space-separated list.
description is the title; extended is the longer note.

Endpoint	What it does	Key parameters
`/tags/get`	All tags with counts	—
`/tags/rename`	Rename a tag	`old`, `new`
`/tags/delete`	Delete a tag	`tag`

User

Endpoint	What it does
`/user/api_token`	Confirms your token works

Rate limits

To keep the service fast for everyone:

Reads: 300 requests per minute.
Writes: 120 requests per minute.
/posts/all: once every 5 minutes (it's expensive — cache the result and use /posts/update to decide when to refetch, exactly as you would on Pinboard).

Over the limit returns HTTP 429.

Migrating an existing script

In most Pinboard scripts you only need to change the API host from api.pinboard.in to www.cowpin.com and use a Cowpin token. The request paths, parameters, and response shapes are the same. If you hit a difference that isn't documented here, that's a compatibility bug — tell us and we'll fix it.