API Documentation — Homogamous

Submit entries programmatically. Authenticate by signing in via the web UI first — your session cookie is used for API auth.

POST /api/subset/entries

Submit or update your entries for a subset.

Request Body

{
  "slug": "wiki",
  "items": [
    "Quantum entanglement",
    "Gödel's incompleteness theorems",
    "Category theory",
    "Kolmogorov complexity",
    "Cellular automaton",
    "Emergence",
    "Turing completeness"
  ]
}

Fields

Field	Type	Description
`slug`	string	The subset slug (e.g. `"wiki"`, `"studyfields"`)
`items`	string[]	Array of exactly N strings (default 7). Each max 200 chars.

Responses

Status	Description
`201`	Created — first submission for this subset
`200`	Updated — replaced existing entries
`400`	Bad request — invalid body, wrong item count, items too long
`401`	Unauthorized — not signed in
`404`	Subset not found
`502`	Embedding server unreachable

Success Response

{
  "ok": true,
  "vectorId": "wiki:42",
  "subset": { "slug": "wiki", "name": "Wikipedia" },
  "items": ["Quantum entanglement", ...]
}

Headers

Header	Required	Description
`Content-Type`	Yes	`application/json`
`X-Homogamous-API`	Cross-origin only	Set to `1` for requests from external origins
`Cookie`	Yes	Your `hg_uid` session cookie

Example

curl -X POST https://homogamous.com/api/subset/entries \
  -H "Content-Type: application/json" \
  -H "X-Homogamous-API: 1" \
  -H "Cookie: hg_uid=YOUR_SESSION" \
  -d '{
    "slug": "wiki",
    "items": ["Item 1", "Item 2", "Item 3", "Item 4", "Item 5", "Item 6", "Item 7"]
  }'

GET /api/subset/vector?id=vectorId

Get vector metadata for one of your entries.

Query Parameters

Param	Type	Description
`id`	string	The vectorId (e.g. `wiki:42`)

Response

{
  "vectorId": "wiki:42",
  "subset": { "slug": "wiki", "name": "Wikipedia" },
  "items": ["Quantum entanglement", ...],
  "dim": 384,
  "createdAt": "2026-06-24T...",
  "updatedAt": "2026-06-24T..."
}