The HTTP endpoint

The endpoint is off until you turn it on, and when it is on it binds to the loopback interface and nothing else. There is no token, because nothing outside the machine can reach it, and there is no write path: it answers searches and returns nothing else.

Turning it on

Set a port in the settings file, or pass --serve when you start the daemon. The endpoint binds to 127.0.0.1 only; there is no configuration that makes it listen elsewhere.

[serve]
port = 7433

Making a request

One endpoint, one required parameter. The response is JSON with a ranked hits array.

# ranked hits, newest first on a tie
curl '127.0.0.1:7433/search?q=invoice' | jq '.hits[].path'

// no client library needed
const res = await fetch('http://127.0.0.1:7433/search?q=invoice');
const { hits } = await res.json();
console.log(hits.map((h) => h.path));

import httpx

r = httpx.get('http://127.0.0.1:7433/search', params={'q': 'invoice'})
for hit in r.json()['hits']:
    print(hit['path'], hit['score'])

Parameters

Anything the query syntax accepts can go in q. The rest are optional.

Wiring an editor to it

1. Start the daemon with the app. Enable Launch at login in settings, or run quarry daemon --serve from a service file.
2. Point the plugin at the port. Each plugin takes a base URL. Keep the default port unless something else already holds it.
3. Check it answers. A request with no q returns 400 and a one-line reason, which is enough to confirm the wiring.

Errors

Failures come back as JSON with the same shape as a hit list, minus the hits. The status code carries the meaning; see Exit codes for the command line equivalents.

{ "error": "missing_query", "detail": "q is required" }