# 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

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

Response (200):

{
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJzb3J0IjoiaW5zZXJ0ZWRfYXQiLCJ0cyI6IjIwMjYtMDMtMjhUMTI6MzQ6NTZaIiwiaWQiOjEyM30",
  "entries": [ ... ]
}

### 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:

• 400 - missing/empty q or query exceeds 1000 bytes

### 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:

• 404 - entry not found or belongs to another user

### 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:

• 404 - entry not found or belongs to another user
• 422 - invalid source_type or field too long

### 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:

• 404 - entry not found or belongs to another user
• 422 - invalid status/strength, or source_id not on this entry

### 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:

• 422 - missing content, validation error, duplicate, or a non-object source

## notes

• Entry types are "link" (has a URL) or "note" (plain text).
• New entries are processed asynchronously. The processing_state field tracks progress: new → processing_url → classifying → generating_embedding → complete (or error).
• Search results are ordered by relevance. Up to 25 results returned.
• The url field is null for notes.
• CORS is enabled for all origins.

links.rip