Current HTTP surface

API reference

Hoardcore has one public, agent-facing write endpoint today. The rest of the application uses authenticated TanStack Start server functions, which are not a stable external API. This page describes what is implemented, not a proposed API.

View OpenAPI 3.1 specification →The spec describes an operator-hosted app API; hoardcore.com hosts documentation only.

Agent endpoint

`POST /api/research/import`

Submit a versioned ResearchResult for a research packet that the same user already created in the app. Create a revocable token under Settings → Research API tokens; copy it when issued, since the value is not shown again. The token has the research:write scope and belongs to its creating user.

AuthenticationBearer research token

Content typeapplication/json

Maximum body5,000,000 bytes

Success201 Created

curl -X POST 'https://YOUR-APP.example/api/research/import' \
  -H 'Authorization: Bearer YOUR_RESEARCH_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-binary @research-result.json

The JSON file must wrap the result as { "result": { ...ResearchResult } }. A valid response contains id, status, and comparableCount; an identical repeated submission may also return idempotent: true. Missing, revoked, expired, or insufficient tokens receive 401. Oversize bodies receive 413; malformed or non-importable results receive 400.

Versioned interchange

ResearchResult 1.0

Export a packet from selected listings in Hoardcore first. Keep its packetId, all version fields, and immutable record references exactly as issued. A result must belong to a packet owned by the token's user. Research data may be valid or partial; invalid results are not imported.

{
  "result": {
    "resultVersion": "1.0",
    "packetVersion": "1.0",
    "promptVersion": "1.0",
    "schemaVersion": "1.0",
    "packetId": "PACKET_ID_FROM_EXPORT",
    "resultId": "YOUR_STABLE_RESULT_ID",
    "completedAt": "2026-01-01T12:00:00Z",
    "records": [{
      "reference": { "entityType": "source_listing", "hoardcoreId": "REFERENCE_FROM_PACKET" },
      "status": "valid",
      "claims": [], "marketEstimates": [], "comparables": [],
      "risks": [], "citations": [], "diagnostics": []
    }]
  }
}

For comparable prices, use comparables with a stable comparableId, channel, evidenceType (active_asking, completed_sale, or retail_offer), nonnegative numeric price, and three-letter currency. Optional evidence includes shipping, condition, observed/sold timestamps, sample size/window, URL, citation ID, and notes. Prices accept at most two decimal places. The versioned Zod schema is the authoritative field-level contract.

Operational routes

Other endpoints

GET /api/health

Public liveness check. Returns { "status": "ok" } when the process responds; it does not check database or worker readiness.

GET /api/ready

Public readiness check. Returns 200 with status: "ready" when PostgreSQL and the embedded worker are ready, otherwise 503.

GET /api/media/{captureId}/{variant}

Requires an app session. captureId is a UUID; variant is thumbnail or preview. Returns the captured image or 404.

/api/auth/*

Authentication routes handled by Better Auth. These are provider/session plumbing, not a Hoardcore agent API; use the configured login flow rather than scripting them.

Important boundary

What is not exposed

There is no stable public API yet for listing search, source management, collection runs, packet creation, watchlists, or alert settings. Use the authenticated app UI for those workflows. A research token cannot access media or general app data, and an ntfy publish token is a separate deployment secret—not a Hoardcore research token.