Hashgrid DNA

DELETE /queries/id/grades/key: forget the query's grade of the item at `key`.

DELETE /: delete the grid and everything in it, items, queries and grades; its key stops working.

DELETE /items/key: delete the item at `key`, and every grade of it.

GET /queries/id/grades/key: the query's grade of the item at `key`.

GET /items/key: the item at `key`, with its `content` as put_item takes it.

GET /items?prefix=: `items`, those whose keys start with `prefix` (e.g. "tools/"; all by default), in key order, without their content (get_item reads one), at most `limit` (1 to 100, 32 by default). `next`: for the next page, pass it as `after` (null: this was the last).

PUT /queries/id/grades/key: grade the item at `key` (as get_results returns it, e.g. "42") for the query `id`. `score` is from -1 (wrong) to 1 (right), anything between for partly right; it trains DNA and replaces the grade before. Grade the results you judged, typically the first few.

PUT /items/key: write the item at `key` (e.g. "42", no leading /), creating it or replacing its content. Text is a string and a record a JSON object, each up to 8 KB; an image its bytes as base64, kept as a WebP of at most 512 px (its width and height come back); an emb a list of floats from the grid's embedder. DNA embeds the rest itself and keeps it only to embed it again; results and listings never return it. `type` is one of text/plain, application/json, image/png, image/jpeg, image/webp, image/gif, application/vnd.hashgrid.emb+json; leave it out for text, a record or an emb, which DNA te…

DELETE /nodes/path: delete the node at `path`, and every grade of it.

GET /nodes/path: the node at `path`, with its `content` as put_node takes it.

PATCH /queries/id/grades: `grades` is a list of {"key": path, "score": s}, for nodes as get_results returns them. A score from -1 (wrong) to 1 (right) trains DNA and replaces the one before; null forgets it.

GET /nodes?prefix=: `nodes`, those whose paths start with `prefix` (e.g. "/items/"), in path order, each with a `preview`: all of its content under 8 KB, else its head (a text's first 8 KB, a record with long values cut, an image's thumbnail), an image as a data: URL, and `truncated`, whether it is less than the content; at most `limit` (1 to 1024). `next`: for the next page, pass it as `after` (null: this was the last).

PUT /nodes/path: write the node at `path` (e.g. "/items/42"), creating it or replacing its content. `type` is one of {TYPES}: text is a string, a record a JSON object, an image its bytes as base64, an emb a list of floats from the grid's embedder. DNA embeds the rest itself. Returns the node: its key, type, size, etag, ctime and mtime.

POST /queries: store a question to ask of the nodes, its content as put_node takes it. Returns its `id`, which the other query tools take. It can be searched with get_results at once.

DELETE /queries/id: delete the query `id` and its grades.

GET /queries/id: the query `id`, with its `content` as create_query takes it.

GET /queries/id/results: the query's best nodes under any of `prefixes` (e.g. ["/items/"]; all nodes by default), best first, each with its `score`, the predicted grade from -1 to 1, and its `preview` as list_nodes shows it. `ungraded`: leave out the nodes it graded. Grade what you judged, and the next results learn from it.

PATCH /queries/id/grades: `grades` is a list of {"key": path, "score": s}, for nodes as get_results returns them. A score from -1 (wrong) to 1 (right) trains DNA and replaces the one before; null forgets it.

GET /queries/id/grades: the query's grades, {"key", "score"}, in path order.

PUT /nodes/path: write the node at `path` (e.g. "/items/42"), creating it or replacing its content. `type` is one of {TYPES}: text is a string, a record a JSON object, an image its bytes as base64, an emb a list of floats from the grid's embedder. DNA embeds the rest itself. Returns the node: its key, type, size, etag, ctime and mtime.

POST /nodes/{nid}/edges, the search: from query node `nid`, the best node it has not been shown yet, among those whose key starts with `prefix` ("" for any), stored as a new edge: `id` is the found node's id, `score` is null until you score it (update_edge). Null when nothing is left. Call again for the next.

POST /nodes: add a node. An item gets a `key`, a path unique in the grid (e.g. "/items/42"), so searches can find it; a query gets none. `emb` is its embedding, 1 to 2048 floats from any model; use one model per grid. Returns its id and key (not its emb, to keep replies short; get_node has it).

DELETE /nodes/{nid}/edges/{eid}: forget a result, so it can be suggested again; its score no longer trains.

GET /nodes/{nid}/edges/{eid}: one result of query `nid`, and its score (null if not scored).

GET /nodes/{nid}/edges: a query's results so far, each an edge with the found node's `id` and its `score` (null if not scored), in id order. `limit` is 1 to 1024; for the next page, pass the last id as `cursor`.

PUT /nodes/{nid}/edges/{eid}: score how well node `eid` fits query `nid`, from -1 (wrong) to 1 (perfect), creating the edge if DNA never suggested it, e.g. scores you already have. Only scores train DNA; a new score replaces the last.

PATCH /nodes/{nid}/edges/{eid}: score a result of query `nid` that create_edge returned, from -1 (wrong) to 1 (perfect). Only scores train DNA; a new score replaces the last.

PATCH /nodes/{nid}: change a node. `key`: a new path, or null to remove it, so the node can no longer be found; leave it out to keep it. `emb`: a new embedding; leave it out to keep it. Its scores keep training, on the new embedding. Returns its id and key.

POST /: create a grid, your own space of nodes and scores; no API key needed. Returns its `api_key`, shown only now: pass it as `api_key` to every other tool, or send it as the header `Authorization: Bearer hg-…`. It holds up to `max_nodes` nodes. Each address may create only a few grids a day.