API Overview

GemInHay exposes three core REST endpoints, all under the v1 API root.

Endpoint	Capability	Use it for
POST /v1/profile/infer-preferences	Preference Inference	Build a "type" model from a user's photos & bio
POST /v1/match/evaluate	Match Evaluation	Score compatibility between two users
POST /v1/conversation/openers	Opener Generation	Generate ice-breaker messages grounded in photos

All endpoints share the same conventions documented below.

Base URL

https://api.geminhay.com

Request headers

Header	Required	Notes
Authorization	yes	Bearer sk_<env>_<secret> — see Authentication
Content-Type	yes	application/json
X-Partner-End-User-Id	optional	SHA-256 of your end-user's ID. Powers per-user analytics in the portal without us ever seeing the raw value.
X-Idempotency-Key	optional	UUID; lets the same request be retried safely

Response shape

Every successful response is a JSON object with a stable schema per endpoint (see the per-endpoint pages). Every error response is:

{
  "error": "<machine_readable_code>",
  "message": "<human readable explanation>",
  "request_id": "req_01H…"
}

Status codes

Status	Meaning
200	Success
400	Validation error (missing/invalid input)
401	Missing or invalid API key
403	Forbidden — usually a key without access to capability
429	Quota exceeded (Free tier) or rate limited
500	Internal error — safe to retry
503	Upstream model temporarily unavailable

Quota headers

Every response includes:

X-GemInHay-Plan: growth
X-GemInHay-Capability: match_evaluation
X-GemInHay-Quota-Used: 12,847
X-GemInHay-Quota-Included: 250,000

Use these to drive your own usage dashboards or to throttle pre-emptively on the client side before bumping into your soft cap.

Rate limits

Per-minute rate limits are enforced per organization × capability at the plan level documented on the Pricing page. Bursting above the limit returns 429 with a Retry-After header in seconds.