API

Indexing API

Crawling covers most content automatically, but some things deserve a direct line into the index: app data, promotions, quick-link shortcuts, or a page you just published. The indexing API writes records immediately, embedded and searchable in one call.

Authentication

Write operations require your admin token. Keep it server-side and never ship it in browser code.

x-hopfield-admin-token: <HOPFIELD_ADMIN_TOKEN>

Index a page by URL

Fetches the URL with the collection’s fetcher and parsing settings, then embeds and indexes it, through the same pipeline as the crawler, one page at a time.

POST /api/collections/{collectionId}/documents

curl -X POST \
  "https://hopfield.io/api/collections/COLLECTION_ID/documents" \
  -H "x-hopfield-admin-token: $HOPFIELD_ADMIN_TOKEN" \
  -H "content-type: application/json" \
  -d '{"url": "https://your-site.com/blog/new-post"}'

Add a manual record or shortcut

Provide the content directly, with no fetching involved. Use it for records that don’t live on a page (database rows, FAQs) and for shortcuts: a title, description, and destination link that should surface for certain queries.

POST /api/collections/{collectionId}/documents

curl -X POST \
  "https://hopfield.io/api/collections/COLLECTION_ID/documents" \
  -H "x-hopfield-admin-token: $HOPFIELD_ADMIN_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "title": "Contact support",
    "description": "Get help from a human",
    "url": "https://your-site.com/support",
    "content": "Contact customer support, help desk, live chat, open a ticket, talk to a human"
  }'

title (required): shown in results.
content (required): the text to embed. Include keywords and synonyms users might type.
url (optional): where the result links. Without it, the record gets a manual:// identifier.
description (optional): shown under the title.

The response reports what happened: { ok, mode, url, chunks, skipped }. Re-posting the same URL updates the existing record in place.

List and delete records

GET / DELETE

# List (supports ?q=, ?limit=, ?offset=)
curl "https://hopfield.io/api/collections/COLLECTION_ID/documents" \
  -H "x-hopfield-admin-token: $HOPFIELD_ADMIN_TOKEN"

# Delete one record
curl -X DELETE \
  "https://hopfield.io/api/collections/COLLECTION_ID/documents/42" \
  -H "x-hopfield-admin-token: $HOPFIELD_ADMIN_TOKEN"

Using the SDK

The same operations are available on HopfieldClient from @hopfield/core when constructed with an adminToken:

import { HopfieldClient } from "@hopfield/core";

const hopfield = new HopfieldClient({
  adminToken: process.env.HOPFIELD_ADMIN_TOKEN,
});

await hopfield.indexPage("COLLECTION_ID", "https://your-site.com/pricing");
await hopfield.indexDocument("COLLECTION_ID", {
  title: "Holiday shipping deadlines",
  content: "Order by Dec 18 for delivery before Dec 24…",
  url: "https://your-site.com/shipping",
});
const { documents } = await hopfield.listDocuments("COLLECTION_ID");
await hopfield.deleteDocument("COLLECTION_ID", documents[0].id);

In the dashboard

Prefer clicking? Every collection’s Records tab has an Add record button with the same two modes: index a page by URL, or add a manual entry/shortcut. See the quickstart.