API Reference

The Hachi API exposes market intelligence from 7 specialized analysis engines via a single, consistent REST interface.

Base URL https://api.hachi.dev

Authentication

All requests to /api/v1/market-analysis must include a valid API key as a Bearer token in the Authorization header.

HTTP Header
Authorization: Bearer hk_live_<your_key>

Get your key from the Dashboard. Free accounts receive 100 requests/month.

Errors

All errors return a JSON body with error (machine code) and message (human text).

HTTP Statuserror codeMeaning
401missing_api_keyNo Authorization header provided.
401invalid_api_keyKey not found or has been revoked.
429quota_exceededMonthly request limit reached.
429demo_limit_reachedFree demo already used today.
400invalid_enginesUnknown engine identifiers provided.
500analysis_failedInternal engine error.

POST /api/v1/market-analysis

Run a full market analysis across one or more Hachi engines. Returns engine signals and the latest synthesized trends from the database.

Request

cURL
curl -X POST https://api.hachi.dev/api/v1/market-analysis \
  -H "Authorization: Bearer hk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"topic":"AI chip shortage","engines":["labor","geopolitical"],"depth":"full"}'
Body fieldTypeRequiredDescription
topicstringNoContext hint for the analysis (max 200 chars).
enginesstring[]NoEngine subset. Omit to use all engines. See Engine IDs.
depthstringNo"summary" (default) or "full". Summary returns 3 trends; full returns 8.

Response

JSON
{
  "success": true,
  "requestedAt": "2026-02-20T14:32:00.000Z",
  "topic": "AI chip shortage",
  "engines": ["labor", "geopolitical"],
  "depth": "summary",
  "usage": {
    "requestsThisMonth": 12,
    "limit": 100,
    "plan": "free"
  },
  "results": {
    "engineSignals": {
      "labor": { ... },
      "geopolitical": { ... }
    },
    "trends": [
      {
        "name": "Semiconductor Labor Crunch",
        "description": "...",
        "term": "short"
      }
    ]
  }
}

POST /api/v1/market-analysis/demo

Run one free analysis per IP address per 24 hours. No API key required — used by the Playground on the home page. Requires a Cloudflare Turnstile captcha token.

cURL
curl -X POST https://api.hachi.dev/api/v1/market-analysis/demo \
  -H "Content-Type: application/json" \
  -d '{"topic":"remote work trends","captchaToken":"<turnstile_token>"}'

GET /api/v1/keys

List all API keys for the authenticated owner. Requires a valid session cookie (set after magic-link sign-in). Never returns the key hash or plaintext.

Response
{
  "success": true,
  "count": 2,
  "keys": [
    {
      "prefix": "hk_live_a1b2",
      "label": "Production",
      "plan": "free",
      "limit": 100,
      "usageCount": 42,
      "monthlyUsage": 12,
      "active": true,
      "lastUsedAt": "2026-02-20T10:00:00.000Z",
      "createdAt": "2026-01-15T08:00:00.000Z"
    }
  ]
}

POST /api/v1/keys

Generate a new API key. The full key is returned once in the response body — it is never stored in plaintext and cannot be retrieved again.

Request body
{ "label": "My production key" }
Response (201)
{
  "success": true,
  "message": "API key created. Copy the key now — it will not be shown again.",
  "key": "hk_live_a1b2c3d4e5f6...",
  "prefix": "hk_live_a1b2",
  "label": "My production key",
  "plan": "free",
  "limit": 100
}

DELETE /api/v1/keys/:prefix

Revoke an API key immediately. All subsequent requests with that key will return 401 invalid_api_key.

cURL
curl -X DELETE https://api.hachi.dev/api/v1/keys/hk_live_a1b2 \
  -H "Cookie: hachi_session=your_session_token"

Engine IDs

Pass any subset of these identifiers in the engines array. Omit to run all.

IDDescription
laborJob postings, skills demand, wage trends via Arbeitnow & Upwork
geopoliticalSanctions, risk events, news signals via NewsAPI & OpenSanctions
consumerConsumer sentiment, trending topics via Hacker News
culturalPop culture, entertainment signals via TMDB & Ticketmaster
environmentalAir quality, climate data via OpenAQ
technologicalGitHub trending, arXiv papers, patent filings

Trend Object

Each trend in the results.trends array conforms to this schema:

TypeScript
interface Trend {
  name: string;                          // Short title
  description: string;                   // 2-3 sentence summary
  extendedDescription?: string;          // Full detail (depth: "full" only)
  term: "short" | "medium" | "long";    // Time horizon
  influenced?: Array<{                   // Adjacent sectors affected
    name: string;
    description: string;
  }>;
  sources?: Array<{                      // Supporting references
    title: string;
    url: string;
    type: string;
  }>;
  charts?: ChartData[];                  // Visualization data
}
© 2026 Hachi API