Pins

A pin places an object in your top of mind — the ordered list of items kept close at hand. Each object can be pinned at most once, so a pin is identified by its object. Pins carry a position that determines their order.

The pin model

Property Type Description
objectId Uid The pinned object. A pin is identified by its object — an object can be pinned at most once.
position integer One-based slot in your top of mind. The first pin is 1; lower positions appear first.

Actions

List pins

Returns your pins, ordered by position. Each is a reference — fetch the objects themselves with List objects.

GET /pins 1 credit

Headers

Header Description
Accept required Either application/json (returns a single array) or application/jsonl (streaming mode — every pin as newline-delimited JSON).
Response 200 OK JSON
[
  {
    "objectId": "a1B2c3D4e5F6g7H8i9J0k1",
    "position": 1
  },
  {
    "objectId": "z9Y8x7W6v5U4t3S2r1Q0p9",
    "position": 2
  }
]
Streaming response 200 OK JSONL
{"objectId":"a1B2c3D4e5F6g7H8i9J0k1","position":1}
{"objectId":"z9Y8x7W6v5U4t3S2r1Q0p9","position":2}

Update pins

Moves pins to new positions. The body is newline-delimited JSON — one patch per line, each naming a pin by its objectId and the position to move it to. Only include the pins you want to move; the rest are left where they are.

PATCH /pins 2 credits

Headers

Header Description
Content-Type required application/jsonl — one JSON patch per line.

Request body

Each line is a complete Pin, applied in the order given. The batch is all or nothing — if any line is rejected, the whole request fails and no pins move.

Property Type Description
objectId required Uid The pin to move. An object that isn't pinned rejects the whole batch with 404 Not Found.
position required integer One-based slot to move the pin to. The first pin is 1; lower positions appear first.
Request
{"objectId":"z9Y8x7W6v5U4t3S2r1Q0p9","position":1}
{"objectId":"a1B2c3D4e5F6g7H8i9J0k1","position":2}
Response 200 OK JSON
{}
Response — rejected batch 404 JSON
{
  "type": "NotFound",
  "status": 404,
  "detail": "Object z9Y8x7W6v5U4t3S2r1Q0p9 is not pinned. No pins were moved."
}