Skip to content

API.md

Latest commit

 

History

History
133 lines (96 loc) · 4.5 KB

API.md

File metadata and controls

133 lines (96 loc) · 4.5 KB
Raw

API Reference

Limelight exposes a local HTTP API on 127.0.0.1:8765 by default. Keep it bound to loopback hosts. Local clients can send X-Origin so the menu bar app can display where a search came from, such as Codex, Claude Code, or OpenCode. Limelight does not use bearer tokens.

Endpoints

  • GET /health
  • GET /v1/schema
  • GET /v1/providers
  • GET /v1/capabilities
  • POST /v1/permissions/request
  • GET /v1/photos/thumbnail?id=PHOTOS-ASSET-UUID
  • GET /v1/item?path=/absolute/path
  • GET /v1/item?source=notes&id=NOTE-ID
  • GET /v1/item?source=mail&id=mail:ROWID
  • POST /v1/open
  • POST /v1/search
  • POST /v1/deep-search
  • POST /v1/ocr
  • POST /v1/extract

Supported type filters are application, document, image, audio, video, folder, archive, and source.

Search

When sources is omitted, the service fans out across every registered provider and returns per-provider statuses. Use sources to constrain the search to one or more providers.

Search files:

curl -s http://127.0.0.1:8765/v1/search \
  -H 'X-Origin: Example Agent' \
  -H 'Content-Type: application/json' \
  -d '{"query":"Codex","sources":["files"],"types":["application"],"onlyIn":["/Applications"],"limit":5}'

Search Photos:

curl -s http://127.0.0.1:8765/v1/search \
  -H 'X-Origin: Example Agent' \
  -H 'Content-Type: application/json' \
  -d '{"query":"receipt","sources":["photos"],"types":["image"],"limit":10}'

Permissions

Request permission prompts or setup guidance:

curl -s http://127.0.0.1:8765/v1/permissions/request \
  -H 'X-Origin: Example Agent' \
  -H 'Content-Type: application/json' \
  -d '{"sources":["contacts","calendar","reminders","photos","mail","notes","safari"]}'

Contacts, Calendar, and Reminders can trigger framework permission prompts. Photos, Mail, Notes, and Safari return Full Disk Access setup instructions because macOS does not expose a programmatic Full Disk Access prompt for those protected stores.

Photos Thumbnails

Fetch a Photos thumbnail:

curl -H 'X-Origin: Example Agent' \
  -o thumbnail.jpg \
  'http://127.0.0.1:8765/v1/photos/thumbnail?id=PHOTOS-ASSET-UUID'

The thumbnail endpoint serves only readable derivative files inside the local Photos library.

Items and Opening

Load file metadata:

curl -s -H 'X-Origin: Example Agent' \
  'http://127.0.0.1:8765/v1/item?path=/Applications/Safari.app'

Load a provider-backed item from a search result. For Notes, use the result id or metadata.noteID; item lookup returns the full decoded note body in item.metadata.body when the private store is readable:

curl -s -H 'X-Origin: Example Agent' \
  'http://127.0.0.1:8765/v1/item?source=notes&id=NOTE-ID'

For Mail, use the search result id such as mail:241231; item lookup returns bounded plain text in item.metadata.bodyExcerpt and item.metadata.bodyText:

curl -s -H 'X-Origin: Example Agent' \
  'http://127.0.0.1:8765/v1/item?source=mail&id=mail:241231'

Open a local file, URL, or provider item on the Mac running Limelight:

curl -s http://127.0.0.1:8765/v1/open \
  -H 'X-Origin: Example Agent' \
  -H 'Content-Type: application/json' \
  -d '{"source":"notes","id":"NOTE-ID"}'

Notes items include a notes://showNote?identifier=... URL when Apple stores a durable note identifier.

Toolbox Endpoints

/v1/deep-search runs multiple query terms and optional regex filters, merges duplicate records, and returns match reasons and scores.

/v1/ocr extracts text lines and full text from a local image path or Photos asset UUID. Set includeText:false to return lines only.

/v1/extract extracts typed entities from supplied text, a local image, a Photos asset, or deep-search results. It can OCR matched image results, return the OCR documents used as context, and save the best result to a local 0600 file. Set includeOCRText:false to suppress OCR text in the response.

Example: find a passport number from Photos results and save it locally:

curl -s http://127.0.0.1:8765/v1/extract \
  -H 'X-Origin: Example Agent' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityTypes":["passport_number"],
    "search":{"queries":["passport"],"sources":["photos"],"limit":50},
    "ocr":{"enabled":true,"maxItems":12,"recognitionLevel":"accurate"},
    "saveTo":"~/Documents/document-number.txt"
  }'

Origin Attribution

Send X-Origin when a client wants its app name to appear in Limelight's recent-search UI:

curl -H 'X-Origin: Codex' http://127.0.0.1:8765/v1/providers