BKMRK — Bookmark Intelligence

You are connected to the user's BKMRK library. BKMRK analyzes bookmarks with Claude AI against the user's coding projects, scoring relevance and generating implementation suggestions.

Terminology: The pipeline statuses are new → staged → done. Always use "stage" / "staged" (never "queue" or "queued") when referring to items the user wants to act on next.

What Gets Analyzed

BKMRK performs deep content extraction across all source types:

• Tweets — full tweet text plus all URLs in the tweet
• X Articles — full article body extracted via X API (not just the title)
• Threads — reconstructed thread text from all replies, plus URLs found in every tweet in the thread (not just the first)
• YouTube videos — full transcript extracted (auto-generated or manual captions), analyzed uncapped regardless of video length
• Blog posts / news articles — full article text extracted via trafilatura, analyzed uncapped
• GitHub repos — README and repo metadata
• Any URL — submitted via the API, fetched and extracted automatically

All content is sent to Claude uncapped for analysis — long articles, 2-hour podcast transcripts, and full X Article bodies all get deep, project-specific analysis.

Authentication

All requests require the user's BKMRK API key as a header:

X-API-Key: {BKMRK_API_KEY}

The API key is available at https://bkmrkapp.com/settings under "Your API Key."

What You Can Do

Browse Library

Browse the analyzed bookmark library with filters. Returns scores, statuses, per-project analyses, and executable prompts. Use this for triaging, browsing, and pipeline management.

GET https://bkmrkapp.com/api/agent/library
X-API-Key: {BKMRK_API_KEY}

All query parameters are optional:

• bookmark_id — Fetch a specific bookmark by UUID (use to check status after submit)
• status — Filter by card status: new, staged, done, trashed
• project_id — Filter by project UUID
• min_score — Minimum relevance score (e.g. 7)
• priority — Filter by priority: high, medium, low
• source — Filter by source: sync (from X bookmarks) or agent (submitted via API)
• limit — Max results (default: 50, max: 100)
• include_project_analyses — Include per-project deep analysis data (default: true)

Examples:

• Unactioned high-value items: ?status=new&min_score=7
• Items staged for a specific project: ?status=staged&project_id=
• Agent-submitted items only: ?source=agent
• Low-priority items for cleanup: ?priority=low&min_score=0

Search Library

Keyword search across titles, explanations, actions, authors, and URLs. Use this when looking for something specific.

POST https://bkmrkapp.com/api/agent/query
Content-Type: application/json
X-API-Key: {BKMRK_API_KEY}

{
  "q": "search terms",
  "project": "ProjectName",
  "priority": "high",
  "status": "new",
  "limit": 10
}

All fields are optional. Returns results sorted by relevance score.

Manage Card Status

Move cards through the pipeline: new → staged → done, or trash/restore them.

POST https://bkmrkapp.com/api/status
Content-Type: application/json
X-API-Key: {BKMRK_API_KEY}

Single item:

{ "bookmark_id": "<uuid>", "status": "staged" }

Batch update:

{ "items": [
    { "bookmark_id": "<uuid>", "status": "done" },
    { "bookmark_id": "<uuid>", "status": "trashed" }
] }

Valid statuses: new, staged, done, trashed (use exact values — "staged" not "stage", "trashed" not "trash"). You can also set "channel": "channel-name" on any item.

Manage Projects

List, create, and update coding projects that bookmarks are analyzed against.

List projects:

GET https://bkmrkapp.com/api/projects
X-API-Key: {BKMRK_API_KEY}

Returns all projects with IDs, names, descriptions, tech stacks, and focus areas. Use this to get project UUIDs for other calls.

Create a project:

POST https://bkmrkapp.com/api/projects
Content-Type: application/json
X-API-Key: {BKMRK_API_KEY}

{
  "name": "My Project",
  "description": "What this project does",
  "tech_stack": ["React", "Node.js"],
  "focus_areas": ["performance", "auth"],
  "analysis_persona": "You are a senior React developer focused on performance optimization and server components.",
  "scoring_bias": "Prioritize: React Server Components, streaming SSR, bundle optimization. Deprioritize: Vue, Angular, jQuery."
}

Optional persona fields:

• analysis_persona — A role description injected into Claude's system prompt when analyzing bookmarks against this project. Makes analysis domain-aware rather than generic. Example: "You are a senior iOS developer focused on SwiftUI patterns, performance optimization, and Claude AI integration for music apps."
• scoring_bias — What topics to weight highly or deprioritize for this project. Example: "Prioritize: SwiftUI, barcode scanning, vinyl/music, AI agents, Claude skills. Deprioritize: web frameworks, marketing tools."

Update a project:

PUT https://bkmrkapp.com/api/projects
Content-Type: application/json
X-API-Key: {BKMRK_API_KEY}

{
  "id": "<project-uuid>",
  "description": "Updated description",
  "tech_stack": ["React", "Next.js"],
  "analysis_persona": "You are a full-stack Next.js engineer...",
  "scoring_bias": "Prioritize: App Router, Server Actions, edge runtime."
}

Deep Analysis

Trigger a deep re-analysis of a bookmark against specific projects. Uses Claude Sonnet for thorough analysis. Returns 202 immediately; results appear in the library within 1-2 minutes.

POST https://bkmrkapp.com/api/reanalyze
Content-Type: application/json
X-API-Key: {BKMRK_API_KEY}

{
  "bookmark_id": "<uuid>",
  "project_ids": ["<project-uuid>"]
}

Returns job_id, credits_used, and credits_remaining. Each project counts as 1 credit. Limits: Free 25/month, Pro 100/month, Scale 500/month.

Understand Context

Get the user's dashboard summary: projects, tier, stats, and library counts.

GET https://bkmrkapp.com/api/context
X-API-Key: {BKMRK_API_KEY}

Returns project list, subscription tier, total bookmarks, items by status, and sync history.

Submit URLs

Send any URL to the library for AI analysis. Supports tweets, YouTube videos, GitHub repos, blog posts, and any web page. Enrichment and analysis run in the background.

POST https://bkmrkapp.com/api/agent/submit
Content-Type: application/json
X-API-Key: {BKMRK_API_KEY}

{
  "url": "https://example.com/interesting-article"
}

Supported URL types:

• Tweet URLs (x.com/user/status/123) — fetches full tweet data, thread context, and all URLs
• YouTube URLs — extracts full video transcript for analysis
• Any other URL — extracts full article text, title, and og:image

Optionally include "project_ids": [""] to analyze against specific projects. Returns 202 with bookmark_id and job_id. Results appear in 1-2 minutes.

Submissions count towards your monthly bookmark cap (Pro 200/month, Scale 500/month). Requires a paid plan.

Create Account (Onboarding)

If the user doesn't have a BKMRK account yet:

POST https://bkmrkapp.com/api/agent/onboard
Content-Type: application/json

{
  "email": "user@example.com",
  "consent": true
}

Returns an API key immediately. No OAuth needed.

Example Agent Workflows

Daily triage

1. GET /api/context — check current state
2. GET /api/agent/library?status=new&min_score=7 — find high-value unactioned items
3. POST /api/status — stage the best ones, trash the noise

Project deep-dive

1. GET /api/projects — get project UUIDs
2. GET /api/agent/library?project_id= — see what's relevant to that project
3. POST /api/reanalyze — deep-analyze items that lack per-project data
4. GET /api/agent/library?project_id= — review enriched results

Bulk cleanup

1. GET /api/agent/library?priority=low&min_score=0 — find low-value items
2. POST /api/status with batch "status": "trashed" — clear them out

Submit and verify

1. POST /api/agent/submit with a URL — returns bookmark_id
2. GET /api/agent/library?bookmark_id= — check status
• If "status": "processing" → analysis still running, wait 30-60s and retry
• If items array has results → analysis complete, show the user the score, explanation, and action

Full API Documentation

For complete endpoint documentation, pricing tiers, and capabilities:

GET https://bkmrkapp.com/agent.json