{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Mythoi tool API", "version": "1.0.0", "description": "Source-grounded mythology research tools. Every response is an envelope carrying source_ids and receipt_url; preserve both when citing a result." }, "servers": [ { "url": "https://mythoi.health" } ], "tags": [ { "name": "Mythoi tools", "description": "The same tools used by REST, MCP, and the Rhapsode." } ], "paths": { "/api/v1/tools": { "get": { "operationId": "listTools", "summary": "List the live Mythoi tools and their JSON schemas", "responses": { "200": { "description": "Live tool inventory", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/tools/motif_lookup": { "get": { "operationId": "motif_lookupGet", "summary": "Run motif_lookup with query parameters", "description": "Look up motifs in the Thompson Motif-Index. Pass tmi_id for an exact address (e.g. 'A1010'), or query to search labels in plain words (e.g. 'flood', 'descent to lower world'). Returns motif rows with their filed-attestation counts.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "tmi_id", "in": "query", "required": false, "description": "Exact Thompson id, e.g. 'A1010'", "schema": { "type": "string", "description": "Exact Thompson id, e.g. 'A1010'" } }, { "name": "query", "in": "query", "required": false, "description": "Plain-words label search, e.g. 'flood'", "schema": { "type": "string", "description": "Plain-words label search, e.g. 'flood'" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "motif_lookup", "summary": "Run motif_lookup with a JSON body", "description": "Look up motifs in the Thompson Motif-Index. Pass tmi_id for an exact address (e.g. 'A1010'), or query to search labels in plain words (e.g. 'flood', 'descent to lower world'). Returns motif rows with their filed-attestation counts.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tmi_id": { "type": "string", "description": "Exact Thompson id, e.g. 'A1010'" }, "query": { "type": "string", "description": "Plain-words label search, e.g. 'flood'" } } } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/attestation_search": { "get": { "operationId": "attestation_searchGet", "summary": "Run attestation_search with query parameters", "description": "Find where a motif lives in the served texts, three lanes in one call: curated attestations (quotable as filed), wired_citations (Thompson's own citation resolved to an exact served chapter — open it with episode_lookup and quote the text), and computed_leads (keyword matches, ~half real — open, confirm the motif is actually in the episode, silently drop the misses). Filter by tmi_id, tradition slug, or work slug — at least one required. This is how you turn an index address into actual story text.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "tmi_id", "in": "query", "required": false, "description": "Thompson id, e.g. 'A1010'", "schema": { "type": "string", "description": "Thompson id, e.g. 'A1010'" } }, { "name": "tradition", "in": "query", "required": false, "description": "Tradition slug, e.g. 'mesopotamian'", "schema": { "type": "string", "description": "Tradition slug, e.g. 'mesopotamian'" } }, { "name": "work", "in": "query", "required": false, "description": "Work slug, e.g. 'gilgamesh'", "schema": { "type": "string", "description": "Work slug, e.g. 'gilgamesh'" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "attestation_search", "summary": "Run attestation_search with a JSON body", "description": "Find where a motif lives in the served texts, three lanes in one call: curated attestations (quotable as filed), wired_citations (Thompson's own citation resolved to an exact served chapter — open it with episode_lookup and quote the text), and computed_leads (keyword matches, ~half real — open, confirm the motif is actually in the episode, silently drop the misses). Filter by tmi_id, tradition slug, or work slug — at least one required. This is how you turn an index address into actual story text.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tmi_id": { "type": "string", "description": "Thompson id, e.g. 'A1010'" }, "tradition": { "type": "string", "description": "Tradition slug, e.g. 'mesopotamian'" }, "work": { "type": "string", "description": "Work slug, e.g. 'gilgamesh'" } } } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/tradition_profile": { "get": { "operationId": "tradition_profileGet", "summary": "Run tradition_profile with query parameters", "description": "Profile a tradition's shelf: its works, episode counts, and how many motif attestations are filed against it. Pass slug (e.g. 'mesopotamian'); omit to list all traditions.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "slug", "in": "query", "required": false, "description": "Tradition slug; omit to list all", "schema": { "type": "string", "description": "Tradition slug; omit to list all" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "tradition_profile", "summary": "Run tradition_profile with a JSON body", "description": "Profile a tradition's shelf: its works, episode counts, and how many motif attestations are filed against it. Pass slug (e.g. 'mesopotamian'); omit to list all traditions.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "Tradition slug; omit to list all" } } } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/episode_lookup": { "get": { "operationId": "episode_lookupGet", "summary": "Run episode_lookup with query parameters", "description": "Read an episode of a work. Pass work (slug, e.g. 'gilgamesh') and optionally canonical_ref (e.g. 'Tablet XI'). Omit canonical_ref for a bounded, offset-paginated contents list with exact total/truncation state. Returns episode text when its license permits public display; otherwise the reference + provenance pointer only.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "work", "in": "query", "required": true, "description": "Work slug, e.g. 'gilgamesh'", "schema": { "type": "string", "description": "Work slug, e.g. 'gilgamesh'" } }, { "name": "canonical_ref", "in": "query", "required": false, "description": "e.g. 'Tablet XI'; omit to list the work's episodes", "schema": { "type": "string", "description": "e.g. 'Tablet XI'; omit to list the work's episodes" } }, { "name": "limit", "in": "query", "required": false, "description": "Contents-page size when canonical_ref is omitted (default/max 100)", "schema": { "type": "number", "minimum": 1, "maximum": 100, "description": "Contents-page size when canonical_ref is omitted (default/max 100)" } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based contents offset when canonical_ref is omitted", "schema": { "type": "number", "minimum": 0, "maximum": 100000, "description": "Zero-based contents offset when canonical_ref is omitted" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "episode_lookup", "summary": "Run episode_lookup with a JSON body", "description": "Read an episode of a work. Pass work (slug, e.g. 'gilgamesh') and optionally canonical_ref (e.g. 'Tablet XI'). Omit canonical_ref for a bounded, offset-paginated contents list with exact total/truncation state. Returns episode text when its license permits public display; otherwise the reference + provenance pointer only.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "work": { "type": "string", "description": "Work slug, e.g. 'gilgamesh'" }, "canonical_ref": { "type": "string", "description": "e.g. 'Tablet XI'; omit to list the work's episodes" }, "limit": { "type": "number", "minimum": 1, "maximum": 100, "description": "Contents-page size when canonical_ref is omitted (default/max 100)" }, "offset": { "type": "number", "minimum": 0, "maximum": 100000, "description": "Zero-based contents offset when canonical_ref is omitted" } }, "required": [ "work" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/motif_neighbors": { "get": { "operationId": "motif_neighborsGet", "summary": "Run motif_neighbors with query parameters", "description": "The knowledge graph around one motif: the traditions Thompson filed it under (his index apparatus, ~49k labeled citations), its place in the index hierarchy, his curated cross-references ('travels with'), ATU tale types, the served episodes it is attested in ('attested_in' — live receipted attestations only, each row carrying its own source_ids and receipt, so a graph walk ends at readable text), and a separately labeled bounded computed co-occurrence layer ('keeps company with'). Computed company is not equivalence or hierarchy. Use for 'what keeps company with X', 'which traditions carry X', and for finding the one thread worth opening.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "tmi_id", "in": "query", "required": true, "description": "Thompson id, e.g. 'A1010'", "schema": { "type": "string", "description": "Thompson id, e.g. 'A1010'" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "motif_neighbors", "summary": "Run motif_neighbors with a JSON body", "description": "The knowledge graph around one motif: the traditions Thompson filed it under (his index apparatus, ~49k labeled citations), its place in the index hierarchy, his curated cross-references ('travels with'), ATU tale types, the served episodes it is attested in ('attested_in' — live receipted attestations only, each row carrying its own source_ids and receipt, so a graph walk ends at readable text), and a separately labeled bounded computed co-occurrence layer ('keeps company with'). Computed company is not equivalence or hierarchy. Use for 'what keeps company with X', 'which traditions carry X', and for finding the one thread worth opening.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tmi_id": { "type": "string", "description": "Thompson id, e.g. 'A1010'" } }, "required": [ "tmi_id" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/compare_traditions": { "get": { "operationId": "compare_traditionsGet", "summary": "Run compare_traditions with query parameters", "description": "THE STITCH, as one call: every witness of a motif AND its child motifs (the whole story-shape family), grouped by tradition — curated attestations, wired Thompson citations resolved to served chapters, and the top computed leads (read-and-discard applies). Each witness carries its work, reference, and composition era. Use for 'which traditions carry X', 'compare X across cultures', and as the skeleton of any cross-tradition telling; open the best 2–4 witnesses with episode_lookup to quote.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "tmi_id", "in": "query", "required": true, "description": "Thompson id, e.g. 'A1010' — find it with motif_lookup first", "schema": { "type": "string", "description": "Thompson id, e.g. 'A1010' — find it with motif_lookup first" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "compare_traditions", "summary": "Run compare_traditions with a JSON body", "description": "THE STITCH, as one call: every witness of a motif AND its child motifs (the whole story-shape family), grouped by tradition — curated attestations, wired Thompson citations resolved to served chapters, and the top computed leads (read-and-discard applies). Each witness carries its work, reference, and composition era. Use for 'which traditions carry X', 'compare X across cultures', and as the skeleton of any cross-tradition telling; open the best 2–4 witnesses with episode_lookup to quote.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tmi_id": { "type": "string", "description": "Thompson id, e.g. 'A1010' — find it with motif_lookup first" } }, "required": [ "tmi_id" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/myth_timeline": { "get": { "operationId": "myth_timelineGet", "summary": "Run myth_timeline with query parameters", "description": "THE LONG AXIS: the same witnesses as compare_traditions but ordered by composition era, oldest first — watch a story-shape move through time from clay tablet to novel. Composition date is when the WITNESS was fixed in writing, not the story's age; the tool's rows say so. Use for 'did X change over time', 'what is the oldest version of X', era-spanning questions.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "tmi_id", "in": "query", "required": true, "description": "Thompson id, e.g. 'A1010'", "schema": { "type": "string", "description": "Thompson id, e.g. 'A1010'" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "myth_timeline", "summary": "Run myth_timeline with a JSON body", "description": "THE LONG AXIS: the same witnesses as compare_traditions but ordered by composition era, oldest first — watch a story-shape move through time from clay tablet to novel. Composition date is when the WITNESS was fixed in writing, not the story's age; the tool's rows say so. Use for 'did X change over time', 'what is the oldest version of X', era-spanning questions.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tmi_id": { "type": "string", "description": "Thompson id, e.g. 'A1010'" } }, "required": [ "tmi_id" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/commentary_search": { "get": { "operationId": "commentary_searchGet", "summary": "Run commentary_search with query parameters", "description": "THE SYMBOLIZE LANE: full-text search restricted to the commentary shelves — early psychology (Jung 1916, Freud), comparative scholarship (Tylor, Harrison, Frazer), and the alchemical corpus. Use when the question asks what something MEANS or SYMBOLIZES: quote these voices as dated commentary ('Tylor argued in 1871...'), never blended into a tale's own voice, and keep the boundary audible. The post-1930 moderns are not here and never quoted — name-only, with library_lookup for cite-and-locate.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search terms, e.g. 'serpent symbol rebirth'", "schema": { "type": "string", "description": "Search terms, e.g. 'serpent symbol rebirth'" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "commentary_search", "summary": "Run commentary_search with a JSON body", "description": "THE SYMBOLIZE LANE: full-text search restricted to the commentary shelves — early psychology (Jung 1916, Freud), comparative scholarship (Tylor, Harrison, Frazer), and the alchemical corpus. Use when the question asks what something MEANS or SYMBOLIZES: quote these voices as dated commentary ('Tylor argued in 1871...'), never blended into a tale's own voice, and keep the boundary audible. The post-1930 moderns are not here and never quoted — name-only, with library_lookup for cite-and-locate.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search terms, e.g. 'serpent symbol rebirth'" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/episode_search": { "get": { "operationId": "episode_searchGet", "summary": "Run episode_search with query parameters", "description": "Full-text search across the complete text of EVERY served episode — all works, all traditions, all shelves at once (primary myth, literary, commentary, alchemical; each hit labeled by work_class). Use when the question's words are not Thompson's index language: an image, an object, a phrase, a name. Space-separated terms must all match; falls back to any-term when nothing carries them together. Matches are in each translator's English and spellings of names vary by edition (Väinämöinen/Wainamoinen) — retry a missed name under another spelling before concluding absence. Rows corroborated by filed motif evidence (Thompson index wiring and curated attestations) rank ahead of raw text coincidence and say so in matched_via; every row carries its own source_ids and a receipt_url where one is filed. Follow a hit with episode_lookup and quote from the full episode, never from the snippet alone.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search terms, e.g. 'wolf swallows sun'", "schema": { "type": "string", "description": "Search terms, e.g. 'wolf swallows sun'" } }, { "name": "work", "in": "query", "required": false, "description": "Optional work slug to search within, e.g. 'kalevala'", "schema": { "type": "string", "description": "Optional work slug to search within, e.g. 'kalevala'" } }, { "name": "tradition", "in": "query", "required": false, "description": "Optional tradition slug to search within, e.g. 'norse'", "schema": { "type": "string", "description": "Optional tradition slug to search within, e.g. 'norse'" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "episode_search", "summary": "Run episode_search with a JSON body", "description": "Full-text search across the complete text of EVERY served episode — all works, all traditions, all shelves at once (primary myth, literary, commentary, alchemical; each hit labeled by work_class). Use when the question's words are not Thompson's index language: an image, an object, a phrase, a name. Space-separated terms must all match; falls back to any-term when nothing carries them together. Matches are in each translator's English and spellings of names vary by edition (Väinämöinen/Wainamoinen) — retry a missed name under another spelling before concluding absence. Rows corroborated by filed motif evidence (Thompson index wiring and curated attestations) rank ahead of raw text coincidence and say so in matched_via; every row carries its own source_ids and a receipt_url where one is filed. Follow a hit with episode_lookup and quote from the full episode, never from the snippet alone.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search terms, e.g. 'wolf swallows sun'" }, "work": { "type": "string", "description": "Optional work slug to search within, e.g. 'kalevala'" }, "tradition": { "type": "string", "description": "Optional tradition slug to search within, e.g. 'norse'" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/tale_type_lookup": { "get": { "operationId": "tale_type_lookupGet", "summary": "Run tale_type_lookup with query parameters", "description": "Look up ATU tale types — the plot-skeleton index (Aarne–Thompson–Uther). Pass atu_id for an exact number (e.g. '425', '425A') or query to search type names ('lost husband'). Returns number, name, category, and how many motifs the record links into the type. Full Uther descriptions are not served (license) — numbers and names are the served facts; the motifs and their texts carry the substance.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "atu_id", "in": "query", "required": false, "description": "Exact ATU number, e.g. '425A'", "schema": { "type": "string", "description": "Exact ATU number, e.g. '425A'" } }, { "name": "query", "in": "query", "required": false, "description": "Type-name search, e.g. 'lost husband'", "schema": { "type": "string", "description": "Type-name search, e.g. 'lost husband'" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "tale_type_lookup", "summary": "Run tale_type_lookup with a JSON body", "description": "Look up ATU tale types — the plot-skeleton index (Aarne–Thompson–Uther). Pass atu_id for an exact number (e.g. '425', '425A') or query to search type names ('lost husband'). Returns number, name, category, and how many motifs the record links into the type. Full Uther descriptions are not served (license) — numbers and names are the served facts; the motifs and their texts carry the substance.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "atu_id": { "type": "string", "description": "Exact ATU number, e.g. '425A'" }, "query": { "type": "string", "description": "Type-name search, e.g. 'lost husband'" } } } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/library_quote": { "get": { "operationId": "library_quoteGet", "summary": "Run library_quote with query parameters", "description": "Quote from the OWNED research library: mythoi's own shelf first (new acquisitions like Thompson's revised Motif-Index), then seba's across the seam (Jung CW, Campbell, Hillman, von Franz, Edinger). Full-text search returning excerpts with author/title/year; pass expand=true for the fuller passage around a hit. THE FOUNDER'S FAIR-USE RULE: quote up to 400 words at a time, ALWAYS cited inline (author, work, year). Frame as the commentator's argument, never the record's claim or the tale's voice. Chat answers only; served pages remain public-domain.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "What you want the depth tradition's voice on, e.g. 'hero journey threshold' or 'ouroboros'", "schema": { "type": "string", "description": "What you want the depth tradition's voice on, e.g. 'hero journey threshold' or 'ouroboros'" } }, { "name": "author", "in": "query", "required": false, "description": "Optional author filter, e.g. 'Jung' or 'Campbell'", "schema": { "type": "string", "description": "Optional author filter, e.g. 'Jung' or 'Campbell'" } }, { "name": "expand", "in": "query", "required": false, "description": "true = include the fuller passage (~400 words) around each hit", "schema": { "type": "boolean", "description": "true = include the fuller passage (~400 words) around each hit" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "library_quote", "summary": "Run library_quote with a JSON body", "description": "Quote from the OWNED research library: mythoi's own shelf first (new acquisitions like Thompson's revised Motif-Index), then seba's across the seam (Jung CW, Campbell, Hillman, von Franz, Edinger). Full-text search returning excerpts with author/title/year; pass expand=true for the fuller passage around a hit. THE FOUNDER'S FAIR-USE RULE: quote up to 400 words at a time, ALWAYS cited inline (author, work, year). Frame as the commentator's argument, never the record's claim or the tale's voice. Chat answers only; served pages remain public-domain.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "What you want the depth tradition's voice on, e.g. 'hero journey threshold' or 'ouroboros'" }, "author": { "type": "string", "description": "Optional author filter, e.g. 'Jung' or 'Campbell'" }, "expand": { "type": "boolean", "description": "true = include the fuller passage (~400 words) around each hit" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/consult_the_record": { "get": { "operationId": "consult_the_recordGet", "summary": "Run consult_the_record with query parameters", "description": "Consult the philological record at logoi.health — the sibling house of WORDS (audited ancient-language corpus: lemmas, passages, concordances, lexicon senses). Call when a question turns on what an ancient WORD means or does, beyond this record ('what does thumos actually mean', 'where does menis occur'). Fast corpus lookups over the family lane, NOT a conversation — results carry logoi's receipts, which you attribute as the record's and quote verbatim. If it returns nothing and the visitor didn't ask for the word-desk, proceed without mentioning the crossing; if the visitor asked directly and it fails, say the crossing failed — never guess at word meanings.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "mode", "in": "query", "required": true, "description": "lemma: a soul-word by normalized slug (e.g. 'thumos', 'psyche'). passage: a citation (e.g. 'Iliad 1.1'). concordance: where a lemma occurs across their corpus. semantic: similarity search for a theme (verify before citing).", "schema": { "type": "string", "enum": [ "lemma", "passage", "concordance", "semantic" ], "description": "lemma: a soul-word by normalized slug (e.g. 'thumos', 'psyche'). passage: a citation (e.g. 'Iliad 1.1'). concordance: where a lemma occurs across their corpus. semantic: similarity search for a theme (verify before citing)." } }, { "name": "language", "in": "query", "required": false, "description": "Language slug; defaults to 'greek'.", "schema": { "type": "string", "description": "Language slug; defaults to 'greek'." } }, { "name": "query", "in": "query", "required": true, "description": "The lemma slug, citation, or theme — depending on mode.", "schema": { "type": "string", "description": "The lemma slug, citation, or theme — depending on mode." } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "consult_the_record", "summary": "Run consult_the_record with a JSON body", "description": "Consult the philological record at logoi.health — the sibling house of WORDS (audited ancient-language corpus: lemmas, passages, concordances, lexicon senses). Call when a question turns on what an ancient WORD means or does, beyond this record ('what does thumos actually mean', 'where does menis occur'). Fast corpus lookups over the family lane, NOT a conversation — results carry logoi's receipts, which you attribute as the record's and quote verbatim. If it returns nothing and the visitor didn't ask for the word-desk, proceed without mentioning the crossing; if the visitor asked directly and it fails, say the crossing failed — never guess at word meanings.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "lemma", "passage", "concordance", "semantic" ], "description": "lemma: a soul-word by normalized slug (e.g. 'thumos', 'psyche'). passage: a citation (e.g. 'Iliad 1.1'). concordance: where a lemma occurs across their corpus. semantic: similarity search for a theme (verify before citing)." }, "language": { "type": "string", "description": "Language slug; defaults to 'greek'." }, "query": { "type": "string", "description": "The lemma slug, citation, or theme — depending on mode." } }, "required": [ "mode", "query" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/consult_the_analysts": { "get": { "operationId": "consult_the_analystsGet", "summary": "Run consult_the_analysts with query parameters", "description": "CONSULT THE ANALYSTS — the estate's depth-psychology commentary shelf (the oracle the seba house reads: Jung's collected works, von Franz, Hillman, Edinger, Neumann and kin). Call when a question turns on what a story MEANS psychologically — a dream-image, a mythic pattern in a person's material, a depth-psychological reading beyond the public-domain commentary shelf. Returns dated commentary attributed by author and year: introduce each analyst per the gloss law, quote as the commentator's argument ('Jung argued in 1952…'), never blended into a tale's own voice, never as the record's claim. Metered: open to members and the family houses only — an access refusal or a failure is NEVER 'no analyst has discussed it'.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "What you want the analysts' voices on, e.g. 'Psyche and Eros as soul-image'", "schema": { "type": "string", "description": "What you want the analysts' voices on, e.g. 'Psyche and Eros as soul-image'" } }, { "name": "top_k", "in": "query", "required": false, "description": "How many voices to return (1-8, default 5)", "schema": { "type": "number", "description": "How many voices to return (1-8, default 5)" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "consult_the_analysts", "summary": "Run consult_the_analysts with a JSON body", "description": "CONSULT THE ANALYSTS — the estate's depth-psychology commentary shelf (the oracle the seba house reads: Jung's collected works, von Franz, Hillman, Edinger, Neumann and kin). Call when a question turns on what a story MEANS psychologically — a dream-image, a mythic pattern in a person's material, a depth-psychological reading beyond the public-domain commentary shelf. Returns dated commentary attributed by author and year: introduce each analyst per the gloss law, quote as the commentator's argument ('Jung argued in 1952…'), never blended into a tale's own voice, never as the record's claim. Metered: open to members and the family houses only — an access refusal or a failure is NEVER 'no analyst has discussed it'.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "What you want the analysts' voices on, e.g. 'Psyche and Eros as soul-image'" }, "top_k": { "type": "number", "description": "How many voices to return (1-8, default 5)" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/library_lookup": { "get": { "operationId": "library_lookupGet", "summary": "Run library_lookup with query parameters", "description": "Search the family research library's holdings (the seba house) by author or title. Returns bibliographic holdings only — author, title, year — for cite-and-locate: you may tell the user the library HOLDS a work and point into it, but its text is never served or quoted here. Use when a question wants the depth tradition's voice (Jung, Hillman, von Franz, Edinger, Campbell...) beyond what the public-domain reference shelf carries.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Author or title fragment, e.g. 'Edinger' or 'Eternal Return'", "schema": { "type": "string", "description": "Author or title fragment, e.g. 'Edinger' or 'Eternal Return'" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "library_lookup", "summary": "Run library_lookup with a JSON body", "description": "Search the family research library's holdings (the seba house) by author or title. Returns bibliographic holdings only — author, title, year — for cite-and-locate: you may tell the user the library HOLDS a work and point into it, but its text is never served or quoted here. Use when a question wants the depth tradition's voice (Jung, Hillman, von Franz, Edinger, Campbell...) beyond what the public-domain reference shelf carries.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Author or title fragment, e.g. 'Edinger' or 'Eternal Return'" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } }, "/api/v1/tools/receipt_get": { "get": { "operationId": "receipt_getGet", "summary": "Run receipt_get with query parameters", "description": "Fetch a receipt by slug when provenance is questioned. Returns the receipt's scope, sources consulted (with licenses and checksums), and evidence notes including what the claim does NOT prove.", "tags": [ "Mythoi tools" ], "parameters": [ { "name": "slug", "in": "query", "required": true, "description": "Receipt slug, e.g. 'attest-a1010-gilgamesh-xi'", "schema": { "type": "string", "description": "Receipt slug, e.g. 'attest-a1010-gilgamesh-xi'" } } ], "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Tool input was not accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } }, "post": { "operationId": "receipt_get", "summary": "Run receipt_get with a JSON body", "description": "Fetch a receipt by slug when provenance is questioned. Returns the receipt's scope, sources consulted (with licenses and checksums), and evidence notes including what the claim does NOT prove.", "tags": [ "Mythoi tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "Receipt slug, e.g. 'attest-a1010-gilgamesh-xi'" } }, "required": [ "slug" ] } } } }, "responses": { "200": { "description": "A provenance-preserving Mythoi tool envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "400": { "description": "Invalid JSON or tool input", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolEnvelope" }, { "$ref": "#/components/schemas/ApiError" } ] } } } }, "429": { "description": "Per-IP or per-house burst limit reached" } } } } }, "components": { "schemas": { "ToolEnvelope": { "type": "object", "required": [ "ok", "tool", "data", "source_ids", "receipt_url" ], "properties": { "ok": { "type": "boolean" }, "tool": { "type": "string" }, "data": {}, "source_ids": { "type": "array", "items": { "type": "string" }, "description": "Provenance row identifiers behind the result." }, "receipt_url": { "type": [ "string", "null" ], "format": "uri", "description": "The filed public receipt when one backs this result." }, "note": { "type": "string", "description": "Honest-empty, truncation, or access-boundary note." }, "family_lane": { "type": "boolean", "description": "Present and true for authenticated sibling-house calls." } } }, "ApiError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }