# links.rip api

Personal link database with hybrid search. Save links, search later.

## authentication

All endpoints require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Generate a token at links.rip/users/settings and store it in the LINKS_RIP_TOKEN environment variable.

export LINKS_RIP_TOKEN="your-token-here"
curl -H "Authorization: Bearer $LINKS_RIP_TOKEN" https://links.rip/api/entries/search?q=example

## endpoints

### GET /api/entries

List entries, newest first. 25 per batch.

GET /api/entries
GET /api/entries?cursor=OPAQUE_CURSOR
GET /api/entries?days=7
GET /api/entries?tag_ids[]=1&tag_ids[]=2
GET /api/entries?stack_id=5
GET /api/entries?feed_id=3
GET /api/entries?intent_status=reading

The cursor is opaque. Pass the next_cursor value from the previous response back unchanged to fetch the next batch.

intent_status keeps only the entries whose current intent has that status: want_to_read, reading, finished, abandoned. Entries with no intent are left out. It combines with the other filters and with cursor.

Response (200):

{
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJzb3J0IjoiaW5zZXJ0ZWRfYXQiLCJ0cyI6IjIwMjYtMDMtMjhUMTI6MzQ6NTZaIiwiaWQiOjEyM30",
  "entries": [
    {
      "id": 91,
      "type": "note",
      "content": "reread the section on backpressure",
      "summary": null,
      "tags": [],
      "processing_state": "complete",
      "url": null,
      "created_at": "2026-03-28T09:00:00Z",
      "intent": {
        "id": 12,
        "status": "reading",
        "strength": "committed",
        "target_at": null,
        "reason": null,
        "source_id": 7,
        "created_at": "2026-03-27T12:00:00Z",
        "updated_at": "2026-03-28T09:00:00Z"
      },
      "intent_source": {
        "id": 7,
        "source_type": "friend",
        "source_name": "Molly",
        "source_ref": null,
        "context": "recommended over coffee",
        "created_at": "2026-03-27T12:00:00Z"
      }
    }
  ]
}

Every listed entry carries intent (your current relationship to it, null for awareness only) and intent_source (the one provenance record named by intent.source_id, null when the intent has none, and always null when intent is). Both objects carry the same fields as under GET /api/entries/:id below. For an entry's full provenance history rather than the single source behind its intent, use that endpoint.

Errors:

### GET /api/entries/search?q=QUERY

Hybrid search across your saved entries. Combines full-text search with semantic vector similarity, ranked by reciprocal rank fusion. Falls back to full-text only if the embedding service is unavailable.

GET /api/entries/search?q=elixir+genserver

Response (200):

{
  "query": "elixir genserver",
  "count": 3,
  "entries": [ ... ]
}

Errors:

### GET /api/entries/:id

Get a single entry by ID.

GET /api/entries/42

Response (200):

{
  "id": 42,
  "type": "link",
  "content": "https://example.com",
  "summary": "...",
  "tags": ["programming"],
  "processing_state": "complete",
  "url": {
    "url": "https://example.com",
    "title": "Example",
    "authority": "example.com"
  },
  "created_at": "2026-03-27T12:00:00Z",
  "sources": [
    {
      "id": 7,
      "source_type": "friend",
      "source_name": "Molly",
      "source_ref": null,
      "context": "recommended over coffee",
      "created_at": "2026-03-27T12:00:00Z"
    }
  ],
  "intent": {
    "id": 12,
    "status": "reading",
    "strength": "committed",
    "target_at": null,
    "reason": null,
    "source_id": 7,
    "created_at": "2026-03-27T12:00:00Z",
    "updated_at": "2026-03-27T12:00:00Z"
  }
}

sources is append-only provenance (how the entry entered the library). intent is your current relationship to it; null means awareness only - no reading commitment.

Errors:

### POST /api/entries/:id/sources

Append a provenance record: how/why this entry entered the library. Sources are append-only; adding one never modifies earlier ones.

POST /api/entries/42/sources
Content-Type: application/json

{
  "source_type": "friend",
  "source_name": "Molly",
  "source_ref": "imessage:abc123",
  "context": "recommended over coffee"
}

source_type is required, one of: self, friend, newsletter, agent, import. The rest are optional.

Response (201): the created source object.

Errors:

### PUT /api/entries/:id/intent

Set your current reading intent for an entry. Creates or fully replaces the single current intent (omitted optional fields are cleared).

PUT /api/entries/42/intent
Content-Type: application/json

{
  "status": "reading",
  "strength": "committed",
  "target_at": "2026-08-01T00:00:00Z",
  "reason": "core reading for the supervision-trees essay",
  "source_id": 7
}

status (required): want_to_read, reading, finished, abandoned. strength (required): ambient, interested, committed. source_id optionally points at the provenance record that created the intent; it must belong to the same entry.

Response (200): the current intent object.

Errors:

### DELETE /api/entries/:id/intent

Remove the current intent, returning the entry to awareness only.

DELETE /api/entries/42/intent

Response: 204 on success, 404 if no intent exists.

### POST /api/entries

Save a link or note.

POST /api/entries
Content-Type: application/json

{ "url": "https://example.com" }
-- or --
{ "content": "some note text" }
-- optionally with declared provenance --
{
  "url": "https://example.com",
  "source": { "source_type": "agent", "source_name": "hermes", "context": "research sweep" }
}

Every new entry records provenance. Without a source object the save is recorded as self; agents saving on someone's behalf should declare agent provenance.

Response (201):

{
  "id": 42,
  "content": "https://example.com",
  "type": "link",
  "created_at": "2026-03-27T12:00:00Z"
}

Errors:

## notes

links.rip