{"service":"Koynay","version":"v1","summary":"Account-scoped access to a library of documents and transcripts, their audio renderings, and the projections (lens-generated graphs) of the Canons those accounts belong to.","auth":{"scheme":"Authorization: Bearer <access key> on every endpoint below except GET /v1 itself","account_selection":"A key may reach several Accounts (an agent key's list). Name one with ?account=<account_id> or header X-Koynay-Account. Fan-out routes answer across every Account the key reaches when none is named, and naming one narrows them: GET /v1/sources, /v1/sources/:sourceId and /v1/sources/:sourceId/text, and the canon-plane routes /v1/search, /v1/grants, /v1/projections (and every /v1/projections/* route) and /v1/mcp. Every other route acts in one Account: a key that reaches more than one and names none is 400 account_required, as on the imports routes. A named Account off the key's list, or without a live membership, is 401 unauthenticated (404 on the imports routes, and for an agent key on POST /v1/sources).","reach":"GET /v1/account answers which Account the key acts in and as whom. Which Canons and lenses a key reaches is per-key data, never listed here: an agent key reaches a Canon only under a grant its holder made, and GET /v1/grants lists the calling key's own.","ceiling":"An agent key is read-only whatever its holder's role, except for playback position and two opt-ins its holder sets separately (both shown on GET /v1/account): imports_enabled lets it import (POST /v1/imports and /v1/imports/check) under the holder's live upload permission, and sources_enabled lets it create a source (POST /v1/sources) under the holder's live source:create permission. Each flag covers only its own route(s) and widens nothing else; neither implies the other."},"grants":{"endpoint":"GET /v1/grants","meaning":"A grant narrows an agent key on the canon plane (graph search and the projection routes) to one Canon or every Canon the key reaches, and one lens or every lens. Grants only subtract: the key's accounts, the holder's live membership, each account's live Canon membership and the read-only ceiling still apply. An agent key without a grant reaches no Canon. Personal and service keys are not governed by grants; their canon-plane reach is membership.","response":"{ key_id, reach: grants | membership, grants: [ grant ] } — only active, unexpired grants are listed","grant":"{ grant_id, canon_id, lens_id, verbs, rate_per_minute, license_class, expires_at, status, created_by_user_id, created_at, revoked_at }","fields":{"canon_id":"a Canon id, or * for every Canon the key reaches","lens_id":"a lens id, or * for every lens; a request that names no lens (graph search without lens_id) is served only by * grants, while a request that names a lens is served by a grant for that lens or *","verbs":"read; propose is reserved and not available","rate_per_minute":"this grant's ceiling, per instance (see rate)","license_class":"member_internal: reason from the material inside the community; do not republish it"},"rate":"Canon-plane responses carry X-Koynay-Rate-Limit, X-Koynay-Rate-Remaining, X-Koynay-Rate-Reset and X-Koynay-Rate-Scope. The ceiling is per grant and per server instance, not a global quota; past it the response is 429 rate_limited with Retry-After.","license":"Every canon-plane response for an agent key states the license_class its material is served under (licenseClass on graph hits and on each canonsSearched entry; license_class on each projection)."},"search":{"endpoint":"GET /v1/search","parameters":{"q":"required keywords; matching is substring, not semantic — spell terms the way the canon's sources spell them","search_type":"passages (default) | graph","lens_id":"optional, graph plane only: search one lens's reading of each Canon (see projections); without it, hits from every lens return together","limit":"1..50, default 20","account":"optional accountId to narrow passage search"},"planes":{"passages":{"purpose":"facts, phrases, quotes — anything you would grep for in raw document text","hit":"{ accountId, accountName, sourceId, title, kind, offset, text }","follow_up":"GET /v1/sources/:sourceId/text for the whole source"},"graph":{"purpose":"conceptual questions answered in the canon's own vocabulary: definitions, distinctions, canonical statements with verbatim grounding","hit":"{ canonId, canonTitle, id, type, loadId, field, snippet, lensId?, projectionId? } — for an agent key also licenseClass; lensId and projectionId are omitted when empty (an Excerpt hit without lens_id)","hit_types":{"Term":"a named concept the canon defines; field=definition hits carry the projection's own definition","Distinction":"the cut that makes a term possible (why X is not Y); prefer for comparison questions","Statement":"canonical discourse employing terms; every statement cites its grounding excerpts","Excerpt":"verbatim canon text with locator — the only layer safe to quote as the source's words"},"discovery":"canonsSearched lists every Canon the key reaches, even with zero hits — for an agent key, only Canons reached under a grant whose lens_id is * (or, with lens_id, that lens), each with grantId and licenseClass; with none, the answer is empty and carries a notice","ids":"Graph hit ids on this route are the ids inside one document's file, so hits from different documents may share an id (two documents' stmt:0001 are different statements). The canon-plane routes under /v1/projections address nodes by load-qualified ids that never collide (each is listed in endpoints once it ships, /v1/projections/search among them); rely on those for anything you store."}},"rules":["Quote only Excerpt text as the source's words; Terms, Distinctions and Statements are a certified reading — attribute them to the canon's graph.","Carry provenance: passage hits cite title + sourceId (+ offset); graph hits cite canonTitle + node id.","An empty graph result is not an absent concept: retry with the canon's likely term or fall through to passage search."]},"lenses":{"meaning":"A lens is a versioned specification of how a canon is read into a graph. One canon can carry several readings; without a filter, graph hits from all of them return together, distinguishable by loadId and lensId. GET /v1/search?search_type=graph takes lens_id to search one reading, and GET /v1/projections lists the readings (Canon, lens) the key reaches.","vocabulary":{"A":"original — CD Spec v2.0 graph identification","B":"distinction-first — the distinction (the cut that makes a term possible) is the atomic unit; statements operate cuts","CSD":"canonical semantic distinctions — experimental single-step relational lens; artifacts are stored but not yet projected into graph search"}},"projections":{"endpoint":"GET /v1/projections","meaning":"A projection is one lens's reading of one Canon at its current membership, named by projection_id. The id changes exactly when what the projection contains changes, so an agent that holds one can tell when the ids it holds may no longer resolve.","parameters":{"canon_id":"optional: list only this Canon's projections"},"response":"{ projections: [ projection ] } — snake_case, like every canon-plane response","projection":"{ canon_id, canon_title, lens_id, lens_title, lens_version, projection_id, documents, grant_id, license_class }","fields":{"documents":"how many of the Canon's documents this lens has read","grant_id":"the grant the key reaches this projection under; null for personal and service keys, whose reach is membership","license_class":"the terms the material is served under (see grants.fields.license_class)"},"reach":"An agent key lists a (Canon, lens) pair only under a grant for that Canon (or *) and that lens (or *); personal and service keys list every lens of every Canon their accounts are members of. A canon_id outside reach lists nothing."},"pack":{"endpoint":"GET /v1/projections/pack","meaning":"The grounding pack: one projection's frame, small enough to hold every turn — its terms, distinctions, concepts, worldview and access, its scope, the relation legend, node types and the rules for reasoning with the tools. Computed by code from the projection; no model writes or selects any part of it. It carries excerpt ids, never excerpt text: fetch evidence with POST /v1/projections/evidence.","parameters":{"canon_id":"required","lens_id":"required","max_tokens":"optional, 2000..15000, default 12000; estimated as ceil(utf8_bytes / 4)"},"response":"{ pack_version, etag, projection_id, canon_id, lens, vocab_version, legend_version, rules_version, manifest_sha256, budget, complete, omitted, discourses, terms, distinctions, concepts, worldviews, access, scope, relation_legend, node_types, rules, license_class, grant_id } — snake_case","budget":"Over budget, imported terms, then supporting terms, are dropped, then term definitions shortened, term excerpt ids dropped and distinction texts shortened, each counted in omitted; complete is false when anything was omitted or the pack is still over budget. Core terms, distinctions, concepts, worldviews, access, scope, the legend and the rules are never dropped.","caching":"ETag: W/\"{etag}.{grant_id or member}\" with Cache-Control: private, no-cache. Send If-None-Match to get 304 when nothing changed; authorization runs first on every request, so a revoked grant is 404 even with a current ETag."},"traversal":{"meaning":"Exact structure and exact evidence from one projection, computed rather than estimated, plus a check of what an answer rests on. Every body is JSON, snake_case, at most 64 KiB, and carries canon_id and lens_id; none of these routes writes anything. Node ids are load-qualified ({load_id}/{local_id}; an excerpt's id is unchanged) and never collide across documents. Every response carries projection_id, license_class and grant_id.","routes":{"neighborhood":"POST /v1/projections/neighborhood { node_ids [1..20], depth? 1..3 (1), direction? both|out|in (both), relations?, node_types?, include_excerpts? (false), limit_nodes? 1..500 (150) } → { projection_id, nodes [node], excerpts [excerpt_ref], edges [edge], truncated }","paths":"POST /v1/projections/paths { from_id, to_id, max_hops? 1..6 (4), relations?, via_evidence? (true), limit_paths? 1..10 (3) } → { projection_id, found, paths [ { length, nodes, edges [ { from, to, relation, direction } ] } ], explored_nodes, complete, unknown } — a path not found is reported, never invented","centrality":"POST /v1/projections/centrality { measure? degree|betweenness|pagerank (degree), node_types?, include_excerpts? (false), relations?, limit? 1..100 (20) } → { projection_id, measure, node_count, edge_count, approximate, by_type, ranking [ { rank, node_id, type, label, score, degree_in, degree_out } ] }","evidence":"POST /v1/projections/evidence { excerpt_ids? [1..50], node_ids? [1..20] (at least one), include_citing_nodes? (true) } → { projection_id, excerpts [excerpt], missing [id], warrant } — unknown ids are listed in missing, not refused","warrant":"POST /v1/projections/warrant { claim (1..4000 characters), citations [1..50] of { excerpt_id?, node_id?, quote? (≤1000), via? pack|traversal|search|entry }, path? [ { from, to, relation } ] (≤20) } → warrant"},"records":{"node":"{ node_id, local_id, type, load_id, label, definition, text, register, aliases, poles, collapsed_as, reveals, source_id, excerpt_ids, concept_id }","excerpt_ref":"{ node_id, type: Excerpt, locator, source_id, cited, text_preview (first 160 characters), sha256 }","edge":"{ from, to, relation, category, load_id }","excerpt":"{ excerpt_id, text (complete, as stored), sha256, locator, source_id, source_title, kind, cited, cited_by }","warrant":"{ warrant_version, warrant_id, standing, projection_id, canon_id, lens_id, manifest_sha256, claim_sha256, nodes, path, excerpts [ { excerpt_id, sha256, locator, source_id } ], checks [ { index, check, passed, detail } ], grant_id, license_class, checked_at }"},"warrant":{"checks":"excerpt_resolves, node_resolves, quote_verbatim (NFC and whitespace-collapsed substring of the stored text), edge_exists (either direction)","standing":"unknown when any check fails or nothing is cited; candidate when every check passes and a citation says via entry; grounded when every check passes and an excerpt is cited with a verbatim quote; interpretation when every check passes on node citations alone","proves":"That every quote is verbatim, every cited id resolves in the projection, every stated path exists, and everything cited was reachable under the key. It does not prove that the claim is a faithful reading of what it cites. The claim is hashed and discarded; nothing is stored."}},"projection_search":{"endpoints":["POST /v1/projections/search","POST /v1/projections/entry"],"meaning":"search finds where the material says something: every excerpt's full text and every node's text, matched by words, not meaning. entry finds candidate nodes from a person's own words by shared spelling; candidates are not findings — confirm one before relying on it, and use search to decide whether the material mentions something.","search_body":"{ q: 1..200 characters, canon_id?, lens_id?, match?: all (default) | any | phrase, node_types?: [type], limit?: 1..50 (20), offset?: 0..500 (0) }","entry_body":"{ text: 1..1000 characters, canon_id?, lens_id?, node_types?: [type], limit?: 1..25 (10), encoder?: hashed-trigram/1 }","node_types":"Concept, Term, Distinction, Statement, Worldview, Frame, Assumption, Access, Competency, Discourse, Excerpt","single":"With canon_id and lens_id, one projection's record. search: { projection_id, query { q, tokens, match }, total_matches, hits [hit], searched { nodes, excerpts }, complete, absence, license_class, grant_ids }. entry: { projection_id, encoder { id, kind, dims }, candidates [candidate], note, license_class, grant_ids }.","fan_out":{"which":"With either omitted, up to ten projections: canon_id only — every lens of that Canon if a grant with lens_id * reaches it; lens_id only — that lens in every Canon reached under it; neither — every lens of every Canon reached under a * lens grant. Personal and service keys reach every lens of every member Canon.","response":"{ projections_searched [ { canon_id, lens_id, projection_id, total_matches } ], projections_skipped [ { canon_id, lens_id, reason } ], projections_failed [ { canon_id, lens_id, code } ], hits [hit + canon_id, lens_id, projection_id], absence, license_class, grant_ids } — entry has candidates (each with canon_id, lens_id, projection_id) in place of hits, encoder and note, and no total_matches or absence","merge":"Scores are not comparable across projections, so results are interleaved, never sorted: each projection's first result in projection order (Canon title, then lens id), then each one's second, and so on; limit applies to the merged list, offset within each projection.","skipped":"reason fan_out_limit: past the ten; lens_scoped_grant_needs_lens_id: a Canon this key reaches only under a lens-limited grant — ask again naming that lens (GET /v1/grants lists it).","failed":"a projection that could not answer, with its error code; the others still answer."},"hit":"{ node_id, type, load_id (\"\" for an Excerpt), label (an Excerpt's locator), field, score, snippet, match_spans [[start, end]], excerpt { locator, source_id, cited, sha256 } | null }","candidate":"{ node_id, type, label, load_id, score 0..1, matched_via text | everyday, candidate: true }","absence":"search only: null unless nothing matched. In the fan-out, present only when every searched projection reported absence and none was skipped or failed. { searched_excerpts, tokens, statement } — with the pack's scope, the evidence that the material does not address something."},"versions":{"endpoint":"POST /v1/projections/versions","meaning":"The versions of a term in one projection: one sense per source, each with that source's own definition, register and aliases, every grounding excerpt verbatim and the statements of the same document that employ it, and the relations an accepted comparison records between the senses — agreement, refinement or disagreement kept as edges, never averaged into one definition. Writes nothing.","body":"{ canon_id, lens_id, node_id } — all required. node_id is a Concept (its member senses) or a Term (its Concept's senses, or the Term alone when it realizes no Concept); any other node type is 400 invalid_request, a node not in the projection 404 node_not_found.","response":"{ projection_id, concept { node_id, label } | null, senses [sense] (by source_id), relations [relation], comparison { sha256, marked_by_user_id, marked_at, produced_by } | null, note, comparison_covers_term, license_class, grant_id } — snake_case","sense":"{ term_node_id, label, definition, register, aliases, load_id, source_id, source_title, doc_title, excerpts [ { excerpt_id, text (complete, as stored), sha256, locator, source_id, source_title, kind, cited } ], statements [ { node_id, text } ] (at most 10, by node_id) }","relation":"{ from, to, relation, category, basis, excerpt_ids, from_load, to_load } — an edge of the accepted comparison with an endpoint among the senses or the statements employing them","no_comparison":"Until a steward accepts a comparison for the lens, relations is empty, comparison is null and note says so. A missing disagreement edge is then not evidence of agreement.","comparison_covers_term":"true | false | null, read from the accepted comparison file itself. true: the file was written against the document of at least one of these senses and at least one other document, so it could record a relation touching them (or the statements employing them); an empty relations then means the file records none — it does not record which terms the steward examined, so this is still not evidence of agreement. false: it could not, so an empty relations says nothing about these senses. null: comparison is null (none accepted), or the graph service does not report it yet. note is unchanged by it."},"mcp":{"endpoint":"POST /v1/mcp","meaning":"The Model Context Protocol face of the canon plane, for agents: the projection routes above as MCP tools, under the same key and the same reach. It adds no authority — every tool is a /v1/projections route the key could call over REST and answers that route's record — and no tool writes.","transport":"MCP Streamable HTTP, stateless: one JSON-RPC 2.0 message per POST. A request is answered 200 application/json with one JSON-RPC response; a notification 202 with no body. No server-sent events and no session (Mcp-Session-Id is neither issued nor read); a JSON array (batch) is refused with -32600. GET and DELETE are 405.","protocol_versions":"2025-06-18. initialize answers with the requested revision when it is supported, otherwise 2025-06-18; an MCP-Protocol-Version header naming an unsupported revision is refused 400.","auth":"Authorization: Bearer <access key> on every request, initialize included; X-Koynay-Account narrows as on every /v1 route. Missing or invalid: 401 unauthenticated with WWW-Authenticate: Bearer realm=\"koynay\". A request carrying an Origin header is refused 403: no browser client is supported.","methods":"initialize, notifications/initialized, ping, tools/list, tools/call, resources/list, resources/read; any other method is -32601","tools":{"list_projections":"GET /v1/projections","get_grounding_pack":"GET /v1/projections/pack","search_text":"POST /v1/projections/search (the tool takes query where the route takes q)","find_entry_points":"POST /v1/projections/entry","get_neighborhood":"POST /v1/projections/neighborhood","find_paths":"POST /v1/projections/paths","rank_nodes":"POST /v1/projections/centrality","get_evidence":"POST /v1/projections/evidence","check_warrant":"POST /v1/projections/warrant","get_term_versions":"POST /v1/projections/versions"},"results":"Success: content [ { type: \"text\", text: the record as JSON } ], structuredContent: the record, isError: false — the record is the REST route's response. A canon-plane failure (the codes under errors) is a result too: content \"<code>: <message>\", structuredContent { error: { code, message } }, isError: true. Arguments that fail a tool's inputSchema, and unknown tools, are JSON-RPC -32602.","resources":"resources/list: one per projection list_projections returns — uri koynay://projections/{canon_id}/{lens_id}/pack, name \"{canon_title} — {lens_title}\", mimeType application/json. resources/read returns that projection's grounding pack (max_tokens 12000) as text; a pack outside reach is -32002.","limits":"Body at most 64 KiB (413 payload_too_large). Each tools/call and resources/read counts once against the grant's per-instance rate (see grants.rate); initialize, ping and the list methods do not."},"imports":{"endpoints":"POST /v1/imports/check (the gates only; stores nothing) and POST /v1/imports (the gates, then store)","who":"An agent key with imports_enabled, or a personal key; either only while the holder's membership in the named Account permits uploads. A service key cannot import. The key's holder is recorded as the person who imported.","account_selection":"?account=<account_id> or X-Koynay-Account, required when the key reaches more than one Account (400 account_required); an Account off the key's list, or without a live membership, is 404.","request":"JSON: { source_id: string | null, title: string | null, canon: string | null, lenses: [ { option, content } ] } — source_id null makes a stub document (title required unless the canon carries source.title); canon is the canon YAML verbatim; one lens entry per catalog option, and CSD options take no canon. At least one of canon, lenses. Unknown fields are refused.","limits":"Each file at most the intake limit (the browser's); the body at most the sum of the limits for the files it names, refused at the first byte past it (413 payload_too_large). Ten imports or checks per minute per key, counted together, per server instance (X-RateLimit-Limit, X-RateLimit-Remaining); past it 429 rate_limited.","check_response":"{ passed, would_create, stub_title, report: [ { file, failures } ] } — 200 whether or not the files pass","import_response":"{ source_id, created, canon: stored | unchanged | null, lenses: [ { option, outcome: stored | unchanged | replaced } ], report } — 200 only when every gate passed and everything was stored","report":"[ { file: canon | option X, failures: [string] } ] — names only the files in the request","rules":["Nothing is stored unless every file passes every gate; a stub made for a refused import is removed in the same request.","A canon is never replaced: a canon that differs from the document's stored one is 400 invalid_request before any gate runs. A lens file may be replaced, and outcome says so.","The gates are the graph service's; an unreachable gate, or one that does not answer within 60 seconds, is 503 graph_unavailable with nothing stored, never an empty report.","Importing never puts a document into a Canon."]},"canons":{"endpoint":"GET /v1/canons","purpose":"Discover canon_id values for POST /v1/sources, and whether this Account's lens-key policy for the canon will build anything (policyLenses empty: nothing builds). It lists the Accounts' Canon memberships, which for an agent key is not its grant reach (see grants).","fields":"{ accountsSearched [{ id, name }], canons [{ accountId, id, title, role, status, canContribute, canManage, createdAt, policyLenses }] }, newest first."},"sources":{"endpoint":"POST /v1/sources","who":"A personal key or a service key, under its own role (source:create); or an agent key with sources_enabled, only while its holder's membership in the named Account permits source:create. For an agent key the holder is recorded as the creator.","account_selection":"?account=<account_id> or X-Koynay-Account, required when the key reaches more than one Account (400 account_required); for an agent key, an Account off the key's list, or without a live membership, is 404.","canon_id":"Allowed for every key that may POST, agent keys with sources_enabled included: the Account must be able to contribute to that Canon (checked before anything is created; otherwise 404 and nothing is stored), and the canon's lens-key policy decides which lenses build.","poll":"After POST with canon_id, GET /v1/sources/:sourceId until every lens in lenses is ready or failed (a failed lens carries its error and errorCode, a short machine code such as api-domain:500:internal, or null) and the canon in canons shows marked: true or a non-null markError. markError { code, message, at } is the last mark into that canon that did not land: stop polling, then fix the cause and resubmit, or give up. Its code is a contribute refusal reason (not_member, suspended, revoked, expired, role_cannot_contribute, membership_unverified: the Account may not contribute to that canon now), validation_failed (the artifacts failed the canon boundary's checks; message lists them), no_canon_artifact (every lens failed, so there was nothing to mark) or mark_failed (any other fault; retrying may help). marked: null means the canon plane could not be asked right now (try again later), and only the first 10 canons are asked per request; a canon the Account can no longer reach has title: null. lenses lists only lens options that have a run; lenses: null means the lens catalog could not be read right now (try again later), unlike {} which means nothing has run.","retry":"After a lens fails (a failed lens carries its error, e.g. a transient provider fault), POST /v1/sources/:sourceId/canons { canon_id } on the same source: it re-requests only lenses whose last run failed or was lost, then poll as above. Never re-create the source to retry; that duplicates it."},"endpoints":{"v1":{"methods":["GET"],"auth":"none","summary":"This document."},"v1/account":{"methods":["GET"],"auth":"key","summary":"The Account this key acts in, as whom, and the agent key's two opt-ins: imports_enabled and sources_enabled (false for every other key)."},"v1/search":{"methods":["GET"],"auth":"key","summary":"Keyword lookup; ?search_type= chooses the passage or graph plane (see search)."},"v1/grants":{"methods":["GET"],"auth":"key","summary":"The calling key's active canon-plane grants (see grants)."},"v1/projections":{"methods":["GET"],"auth":"key","summary":"The projections (Canon, lens) the key reaches, with projection_id; ?canon_id= narrows (see projections)."},"v1/projections/pack":{"methods":["GET"],"auth":"key","summary":"One projection's grounding pack: ?canon_id=&lens_id=[&max_tokens=]; ETag and If-None-Match (see pack)."},"v1/projections/neighborhood":{"methods":["POST"],"auth":"key","summary":"The typed structure around seed nodes (see traversal)."},"v1/projections/paths":{"methods":["POST"],"auth":"key","summary":"Shortest paths between two nodes, or found: false (see traversal)."},"v1/projections/centrality":{"methods":["POST"],"auth":"key","summary":"Nodes ranked by degree, betweenness or pagerank (see traversal)."},"v1/projections/evidence":{"methods":["POST"],"auth":"key","summary":"Excerpts' complete verbatim text with sha256, by excerpt or node id (see traversal)."},"v1/projections/warrant":{"methods":["POST"],"auth":"key","summary":"Check a claim's citations and path; returns a warrant with its standing (see traversal.warrant)."},"v1/projections/search":{"methods":["POST"],"auth":"key","summary":"Lexical search over one projection or a fan-out of up to ten (see projection_search)."},"v1/projections/entry":{"methods":["POST"],"auth":"key","summary":"Candidate entry points from a person's own words, by spelling overlap (see projection_search)."},"v1/projections/versions":{"methods":["POST"],"auth":"key","summary":"The versions of a term: one sense per source, and the relations an accepted comparison records between them (see versions)."},"v1/mcp":{"methods":["POST"],"auth":"key","summary":"The MCP server: the canon-plane routes as tools, one JSON-RPC message per request (see mcp)."},"v1/canons":{"methods":["GET"],"auth":"key","summary":"The Canons the key's Accounts belong to (active memberships; fans out like GET /v1/sources, ?account= narrows): the canon_id values POST /v1/sources accepts. Account membership, not an agent key's grant reach (see canons)."},"v1/sources":{"methods":["GET","POST"],"auth":"key","summary":"GET: the library, cursor-paginated: ?kind=&limit=&cursor=. POST { title, text, kind?, canon_id? } creates a document from text in one Account (201 { source, canon }); canon_id associates it with that Canon as the app's Add to canon does, and the canon's lens-key policy decides what builds. An agent key may POST only when its holder enabled sources_enabled, as its holder (see sources). Each listed item carries canonIds (its canon associations) and lenses ({ option: preparing | ready | failed }), each null when unknown."},"v1/sources/:sourceId":{"methods":["GET"],"auth":"key","summary":"One source's metadata (never embeds the text): { accountId, source, canons: [ { id, title, marked } ], lenses: { option: { state, error, errorCode, model, requestedAt, updatedAt } } } — canons are the source's canon associations, lenses its lens runs (see sources.poll)."},"v1/sources/:sourceId/text":{"methods":["GET"],"auth":"key","summary":"The source's readable text as text/plain."},"v1/sources/:sourceId/audio":{"methods":["GET"],"auth":"key","summary":"The source's audio renderings, newest first."},"v1/sources/:sourceId/canons":{"methods":["POST"],"auth":"key","summary":"Associate an existing source with a Canon (or re-run it): { canon_id }. Idempotent; re-triggers lenses whose last run failed or was lost, never one that is ready or running. Same key rules as POST /v1/sources."},"v1/collections":{"methods":["GET","POST"],"auth":"key","summary":"List the account's collections; POST { title } creates one."},"v1/collections/:collectionId":{"methods":["GET","PATCH","DELETE"],"auth":"key","summary":"One collection with ordered items; PATCH { title } renames; DELETE removes the grouping only."},"v1/collections/:collectionId/items":{"methods":["POST"],"auth":"key","summary":"Append an existing Document to the collection."},"v1/collections/:collectionId/items/:documentId":{"methods":["DELETE"],"auth":"key","summary":"Remove a Document from the collection (the Document is kept)."},"v1/collections/:collectionId/order":{"methods":["PUT"],"auth":"key","summary":"Set the collection's full member order."},"v1/audio/:artifactId":{"methods":["GET"],"auth":"key","summary":"The rendering's MP3 bytes, with Range support."},"v1/audio/:artifactId/timings":{"methods":["GET"],"auth":"key","summary":"Sentence-timing JSON for read-along."},"v1/audio/:artifactId/position":{"methods":["GET","PUT"],"auth":"key","summary":"Resume position for this actor; PUT records it."},"v1/audio/:artifactId/video":{"methods":["GET","POST"],"auth":"key","summary":"The rendered MP4 (Range support); POST requests the render (202)."},"v1/playable":{"methods":["GET"],"auth":"key","summary":"The account's playable set for player clients."},"v1/imports/check":{"methods":["POST"],"auth":"key (imports_enabled)","summary":"Run the import gates on processed files; stores nothing (see imports)."},"v1/imports":{"methods":["POST"],"auth":"key (imports_enabled)","summary":"Import processed files (a canon, lens files, CSD files) through the gates; stores everything or nothing (see imports)."}},"errors":{"format":"{ \"error\": { \"code\": <code>, \"message\": <human text> } }","gate_failed_format":"{ \"error\": { \"code\": \"gate_failed\", \"message\": <human text>, \"report\": [ { \"file\", \"failures\" } ] } } — the only code that adds a field","codes":{"unauthenticated":"401 — missing or invalid key (unknown, expired or revoked, all alike), or a named Account the key does not reach (see auth.account_selection)","invalid_request":"400 — missing or malformed parameter","account_required":"400 — the key reaches more than one Account and the request named none, on a route that acts in one Account: every route except the fan-out routes listed in auth.account_selection (imports included). The message never names the Accounts.","forbidden":"403 — import only: an agent key without imports_enabled, a service key, or a holder whose membership no longer permits uploads; POST /v1/sources only: an agent key without sources_enabled, or a holder whose membership no longer permits source:create; POST /v1/mcp only: the request carried an Origin header (no browser client is supported)","not_found":"404 — also returned when the key reaches nothing readable","method_not_allowed":"405 — wrong verb on an action endpoint","projection_unavailable":"409 — the Canon's projection cannot be rebuilt right now; its stewards can see why","canon_exists":"409 — import only: the document already has a different canon file (compared byte-for-byte, including line endings and a trailing newline); a canon is create-only, so nothing was stored (an identical canon answers canon: unchanged)","node_not_found":"404 — a seed or path endpoint is not in the projection; the message names the ids","payload_too_large":"413 — a request body over 64 KiB; for import, a file over the intake limit or a body over the limits for the files it names","query_too_broad":"422 — a neighborhood whose seeds alone exceed limit_nodes","gate_failed":"422 — import only: at least one gate refused; error.report carries the full report; nothing was stored","rate_limited":"429 — a grant's per-instance ceiling is spent (see grants.rate), or a key's import ceiling (see imports.limits)","graph_unavailable":"503 — the canon plane is not available in this environment, unreachable, or did not answer within 60 seconds"}}}