{"openapi":"3.1.0","info":{"title":"Lore Index API","version":"0.1.0","description":"The REST interface to the Lore Index — a governed, scoped, auditable record of organizational memory for AI agents. Every route runs against the same row-level-scoped services as the MCP tools, so scoping, ranking, authorization, and the append-only audit trail behave identically through either door. All requests are authenticated with a bearer credential and metered per organization."},"servers":[{"url":"https://api-production-b7f69.up.railway.app","description":"Production"},{"url":"http://localhost:3001","description":"Local development"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"entries","description":"The governed record: draft, propose, review, approve, archive."},{"name":"search","description":"Full-text retrieval over active entries in the caller's scopes."},{"name":"pack","description":"The compiled bootstrap pack of binding guidance."},{"name":"identity","description":"The resolved identity and capabilities of the bearer credential."},{"name":"api-keys","description":"Issue and revoke the caller's own API keys."},{"name":"teams","description":"Team registry and membership (admin)."},{"name":"roles","description":"Role registry and membership (admin)."},{"name":"members","description":"Organization members and access levels (admin)."},{"name":"audit","description":"The append-only audit ledger (admin)."},{"name":"import","description":"Bulk ingestion of candidate entries from a document or CSV."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer credential in the `Authorization` header. Two forms are accepted: an API key (`lore_sk_…`; legacy `compass_sk_…` keys remain valid) carrying read / propose / write scopes, or an MCP-issued OAuth 2.1 access token. Browser sessions authenticate with the first-party Better Auth cookie instead."}},"responses":{"Unauthorized":{"description":"Missing or invalid bearer credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"The organization has no active subscription (billing gate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The credential lacks the scope or access level for this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such record in the caller's scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"The request conflicts with the current state (e.g. a stale-write guard or a duplicate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"The per-plan request rate limit was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error body.","properties":{"error":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."}},"required":["error"]},"Entry":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"type":{"type":"string","enum":["instruction","preference","fact","contact","glossary"]},"title":{"type":"string","maxLength":80},"body":{"type":"string","maxLength":1000},"scope":{"type":"string","description":"`org` | `team:<id>` | `role:<id>` | `user:<id>`."},"tags":{"type":"array","items":{"type":"string"}},"priority":{"type":"string","enum":["must","should","context"]},"status":{"type":"string","enum":["draft","pending_review","active","archived"]},"source":{"type":"string"},"expiresAt":{"type":["string","null"],"format":"date-time"},"supersedes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","type","title","body","scope","priority","status"]},"EntryVersion":{"type":"object","description":"An append-only snapshot of an entry at a given version number.","properties":{"id":{"type":"string"},"entryId":{"type":"string"},"version":{"type":"integer"},"type":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"scope":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"priority":{"type":"string"},"status":{"type":"string"},"changedBy":{"type":["string","null"]},"changedAt":{"type":"string","format":"date-time"}},"required":["entryId","version","title","body"]},"SearchResult":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["instruction","preference","fact","contact","glossary"]},"title":{"type":"string"},"body":{"type":"string"},"scope":{"type":"string"},"priority":{"type":"string","enum":["must","should","context"]},"status":{"type":"string","enum":["draft","pending_review","active","archived"]},"tags":{"type":"array","items":{"type":"string"}},"rank":{"type":"number","description":"Relevance score with a priority boost."}},"required":["id","title","priority"]},"Pack":{"type":"object","description":"The compiled bootstrap pack — active MUST/SHOULD guidance for the caller's scopes.","properties":{"markdown":{"type":"string","description":"The pack rendered as markdown."},"tokenCost":{"type":"integer","description":"Estimated token size (characters ÷ 4)."},"tokenCap":{"type":"integer","description":"The org's configured pack token cap."},"stale":{"type":"boolean"},"compiledAt":{"type":["string","null"],"format":"date-time"},"cached":{"type":"boolean"}},"required":["markdown"]},"ApiKey":{"type":"object","description":"An API-key record (never carries the secret or its hash).","properties":{"id":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","propose","write"]}},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","scopes"]},"Team":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","slug"]},"Role":{"type":"object","properties":{"id":{"type":"string"},"orgId":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name"]},"Member":{"type":"object","properties":{"userId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"displayName":{"type":["string","null"]},"role":{"type":"string"},"accessLevel":{"type":"string","enum":["viewer","editor","admin"]},"grants":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["viewer","editor","admin"]},"scope":{"type":["string","null"]}}}},"teamIds":{"type":"array","items":{"type":"string"}},"roleIds":{"type":"array","items":{"type":"string"}},"joinedAt":{"type":"string","format":"date-time"}},"required":["userId","accessLevel"]},"AuditEvent":{"type":"object","description":"One append-only audit ledger row.","properties":{"id":{"type":"string"},"actor":{"type":["string","null"]},"action":{"type":"string"},"objectType":{"type":"string"},"objectId":{"type":["string","null"]},"before":{"type":["object","null"]},"after":{"type":["object","null"]},"at":{"type":"string","format":"date-time"}},"required":["action","objectType","at"]},"ImportCandidate":{"type":"object","description":"One candidate entry produced by the importer, for review before creation.","properties":{"type":{"type":"string","enum":["instruction","preference","fact","contact","glossary"]},"title":{"type":"string","maxLength":80},"body":{"type":"string","maxLength":1000},"tags":{"type":"array","items":{"type":"string"}},"priority":{"type":"string","enum":["must","should","context"]},"scopeHint":{"type":"string","enum":["org","team","role","user"]}},"required":["type","title","body"]},"EntryInput":{"type":"object","properties":{"type":{"type":"string","enum":["instruction","preference","fact","contact","glossary"]},"title":{"type":"string","minLength":1,"maxLength":80},"body":{"type":"string","minLength":1,"maxLength":1000},"scope":{"type":"string","pattern":"^(org|(team|role|user):[0-9A-Za-z_-]+)$"},"tags":{"default":[],"type":"array","items":{"type":"string"}},"priority":{"default":"should","type":"string","enum":["must","should","context"]},"status":{"default":"draft","type":"string","enum":["draft","pending_review","active","archived"]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"supersedes":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","title","body","scope","tags","priority","status"],"additionalProperties":false},"EntryPatch":{"type":"object","properties":{"type":{"type":"string","enum":["instruction","preference","fact","contact","glossary"]},"title":{"type":"string","minLength":1,"maxLength":80},"body":{"type":"string","minLength":1,"maxLength":1000},"scope":{"type":"string","pattern":"^(org|(team|role|user):[0-9A-Za-z_-]+)$"},"tags":{"type":"array","items":{"type":"string"}},"priority":{"type":"string","enum":["must","should","context"]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"additionalProperties":false},"EntriesSubmit":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1}}},"required":["ids"],"additionalProperties":false},"EntriesApprove":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"expectedUpdatedAt":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","format":"date-time"}}},"required":["ids"],"additionalProperties":false},"EntriesReject":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["ids","reason"],"additionalProperties":false},"EntryApprove":{"type":"object","properties":{"expectedUpdatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false},"Reject":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false},"ApiKeyCreate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"scopes":{"minItems":1,"type":"array","items":{"type":"string","enum":["read","propose","write"]}}},"required":["name","scopes"],"additionalProperties":false},"TeamInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"slug":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9-]+$"}},"required":["name","slug"],"additionalProperties":false},"TeamPatch":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"slug":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9-]+$"}},"additionalProperties":false},"RoleInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"],"additionalProperties":false},"Membership":{"type":"object","properties":{"userId":{"type":"string","minLength":1}},"required":["userId"],"additionalProperties":false},"MemberLevel":{"type":"object","properties":{"level":{"type":"string","enum":["viewer","editor","admin"]}},"required":["level"],"additionalProperties":false},"InviteMember":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"level":{"default":"viewer","type":"string","enum":["viewer","editor","admin"]}},"required":["email","level"],"additionalProperties":false},"ImportAnalyze":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":20000}},"required":["text"],"additionalProperties":false},"ImportCsv":{"type":"object","properties":{"csv":{"type":"string","minLength":1,"maxLength":100000}},"required":["csv"],"additionalProperties":false},"ImportBulk":{"type":"object","properties":{"entries":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["instruction","preference","fact","contact","glossary"]},"title":{"type":"string","minLength":1,"maxLength":80},"body":{"type":"string","minLength":1,"maxLength":1000},"scope":{"type":"string","pattern":"^(org|(team|role|user):[0-9A-Za-z_-]+)$"},"tags":{"default":[],"type":"array","items":{"type":"string"}},"priority":{"default":"should","type":"string","enum":["must","should","context"]},"status":{"default":"draft","type":"string","enum":["draft","pending_review","active","archived"]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"supersedes":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","title","body","scope","tags","priority","status"],"additionalProperties":false}},"submitForReview":{"default":false,"type":"boolean"}},"required":["entries","submitForReview"],"additionalProperties":false}}},"paths":{"/v1/entries":{"get":{"tags":["entries"],"summary":"List entries","parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["instruction","preference","fact","contact","glossary"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"One status or a comma-separated list (draft,pending_review,active,archived)."}},{"name":"scope","in":"query","required":false,"schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"schema":{"type":"string"}},{"name":"priority","in":"query","required":false,"schema":{"type":"string","enum":["must","should","context"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of entries and the total matching count.","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["entries"],"summary":"Create an entry","parameters":[{"name":"propose","in":"query","required":false,"schema":{"type":"boolean","description":"When true, the entry lands as pending_review instead of draft/active."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntryInput"}}}},"responses":{"201":{"description":"The created entry.","content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"$ref":"#/components/schemas/Entry"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entries/export":{"get":{"tags":["entries"],"summary":"Export readable entries as CSV","responses":{"200":{"description":"Re-importable CSV of the org's readable entries.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entries/submit":{"post":{"tags":["entries"],"summary":"Submit drafts for review","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntriesSubmit"}}}},"responses":{"200":{"description":"The submitted entries.","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entries/approve":{"post":{"tags":["entries"],"summary":"Bulk-approve pending proposals","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntriesApprove"}}}},"responses":{"200":{"description":"The approved entries.","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entries/reject":{"post":{"tags":["entries"],"summary":"Bulk-reject pending proposals","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntriesReject"}}}},"responses":{"200":{"description":"The rejected entries.","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/Entry"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entries/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Entry id.","schema":{"type":"string"}}],"get":{"tags":["entries"],"summary":"Read one entry","responses":{"200":{"description":"The entry.","content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"$ref":"#/components/schemas/Entry"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"tags":["entries"],"summary":"Update entry fields","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntryPatch"}}}},"responses":{"200":{"description":"The updated entry.","content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"$ref":"#/components/schemas/Entry"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entries/{id}/withdraw":{"parameters":[{"name":"id","in":"path","required":true,"description":"Entry id.","schema":{"type":"string"}}],"post":{"tags":["entries"],"summary":"Withdraw a proposal back to draft","responses":{"200":{"description":"The withdrawn entry.","content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"$ref":"#/components/schemas/Entry"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entries/{id}/archive":{"parameters":[{"name":"id","in":"path","required":true,"description":"Entry id.","schema":{"type":"string"}}],"post":{"tags":["entries"],"summary":"Archive an entry","responses":{"200":{"description":"The archived entry.","content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"$ref":"#/components/schemas/Entry"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entries/{id}/versions":{"parameters":[{"name":"id","in":"path","required":true,"description":"Entry id.","schema":{"type":"string"}}],"get":{"tags":["entries"],"summary":"List an entry's version history","responses":{"200":{"description":"Version snapshots, oldest first.","content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"$ref":"#/components/schemas/EntryVersion"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entries/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Entry id.","schema":{"type":"string"}}],"post":{"tags":["entries"],"summary":"Approve one proposal or draft","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntryApprove"}}}},"responses":{"200":{"description":"The approved entry.","content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"$ref":"#/components/schemas/Entry"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/entries/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Entry id.","schema":{"type":"string"}}],"post":{"tags":["entries"],"summary":"Reject one proposal","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reject"}}}},"responses":{"200":{"description":"The rejected entry and the reason recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"entry":{"$ref":"#/components/schemas/Entry"},"reason":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/search":{"get":{"tags":["search"],"summary":"Full-text search over active entries","parameters":[{"name":"q","in":"query","required":true,"description":"Query text.","schema":{"type":"string","minLength":1}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["instruction","preference","fact","contact","glossary"]}},{"name":"tags","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated tag filter."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Ranked matches.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/bootstrap":{"get":{"tags":["pack"],"summary":"Fetch the compiled bootstrap pack","responses":{"200":{"description":"The caller's bootstrap pack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pack"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/me":{"get":{"tags":["identity"],"summary":"Resolve the caller's identity and capabilities","responses":{"200":{"description":"The resolved identity, scopes, and billing state.","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object"},"orgId":{"type":"string"},"accessLevel":{"type":"string","enum":["viewer","editor","admin"]},"scopes":{"type":"array","items":{"type":"string"}},"keyScopes":{"type":"array","items":{"type":"string","enum":["read","propose","write"]}},"writableScopes":{"type":"array","items":{"type":"string"}},"teams":{"type":"array","items":{"$ref":"#/components/schemas/Team"}},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/api-keys":{"get":{"tags":["api-keys"],"summary":"List the caller's API keys","responses":{"200":{"description":"The caller's keys (no secrets).","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["api-keys"],"summary":"Issue an API key","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"}}}},"responses":{"201":{"description":"The new key — the plaintext secret is returned exactly once.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"The plaintext secret (shown only here)."},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["read","propose","write"]}}},"required":["id","key"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/api-keys/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"API-key id.","schema":{"type":"string"}}],"delete":{"tags":["api-keys"],"summary":"Revoke an API key","responses":{"200":{"description":"The revoked key id.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"revoked":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/teams":{"get":{"tags":["teams"],"summary":"List teams","responses":{"200":{"description":"The org's teams.","content":{"application/json":{"schema":{"type":"object","properties":{"teams":{"type":"array","items":{"$ref":"#/components/schemas/Team"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["teams"],"summary":"Create a team","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamInput"}}}},"responses":{"201":{"description":"The created team.","content":{"application/json":{"schema":{"type":"object","properties":{"team":{"$ref":"#/components/schemas/Team"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/teams/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Team id.","schema":{"type":"string"}}],"patch":{"tags":["teams"],"summary":"Update a team","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamPatch"}}}},"responses":{"200":{"description":"The updated team.","content":{"application/json":{"schema":{"type":"object","properties":{"team":{"$ref":"#/components/schemas/Team"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["teams"],"summary":"Delete a team","responses":{"200":{"description":"The deleted team id.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/teams/{id}/members":{"parameters":[{"name":"id","in":"path","required":true,"description":"Team id.","schema":{"type":"string"}}],"post":{"tags":["teams"],"summary":"Add a member to a team","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Membership"}}}},"responses":{"201":{"description":"The team/user pairing.","content":{"application/json":{"schema":{"type":"object","properties":{"teamId":{"type":"string"},"userId":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/teams/{id}/members/{userId}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Team id.","schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"description":"User id.","schema":{"type":"string"}}],"delete":{"tags":["teams"],"summary":"Remove a member from a team","responses":{"200":{"description":"Removal confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"teamId":{"type":"string"},"userId":{"type":"string"},"removed":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/roles":{"get":{"tags":["roles"],"summary":"List roles","responses":{"200":{"description":"The org's roles.","content":{"application/json":{"schema":{"type":"object","properties":{"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["roles"],"summary":"Create a role","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleInput"}}}},"responses":{"201":{"description":"The created role.","content":{"application/json":{"schema":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/Role"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Role id.","schema":{"type":"string"}}],"patch":{"tags":["roles"],"summary":"Update a role","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleInput"}}}},"responses":{"200":{"description":"The updated role.","content":{"application/json":{"schema":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/Role"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["roles"],"summary":"Delete a role","responses":{"200":{"description":"The deleted role id.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/roles/{id}/members":{"parameters":[{"name":"id","in":"path","required":true,"description":"Role id.","schema":{"type":"string"}}],"post":{"tags":["roles"],"summary":"Add a member to a role","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Membership"}}}},"responses":{"201":{"description":"The role/user pairing.","content":{"application/json":{"schema":{"type":"object","properties":{"roleId":{"type":"string"},"userId":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/roles/{id}/members/{userId}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Role id.","schema":{"type":"string"}},{"name":"userId","in":"path","required":true,"description":"User id.","schema":{"type":"string"}}],"delete":{"tags":["roles"],"summary":"Remove a member from a role","responses":{"200":{"description":"Removal confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"roleId":{"type":"string"},"userId":{"type":"string"},"removed":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/members":{"get":{"tags":["members"],"summary":"List organization members","responses":{"200":{"description":"The org's members with grants, teams, and roles.","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/Member"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/members/invite":{"post":{"tags":["members"],"summary":"Invite a member by email","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteMember"}}}},"responses":{"200":{"description":"The invited/created member.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"userId":{"type":"string"},"level":{"type":"string","enum":["viewer","editor","admin"]},"pending":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/members/{userId}":{"parameters":[{"name":"userId","in":"path","required":true,"description":"User id.","schema":{"type":"string"}}],"patch":{"tags":["members"],"summary":"Set a member's org-wide access level","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberLevel"}}}},"responses":{"200":{"description":"The updated member.","content":{"application/json":{"schema":{"type":"object","properties":{"member":{"$ref":"#/components/schemas/Member"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["members"],"summary":"Remove a member from the organization","responses":{"200":{"description":"Removal confirmation.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/audit":{"get":{"tags":["audit"],"summary":"Read the audit ledger","parameters":[{"name":"objectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"actor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Audit events, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/audit/export":{"get":{"tags":["audit"],"summary":"Export the full audit ledger as CSV","responses":{"200":{"description":"CSV of the org's entire audit ledger.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/import":{"get":{"tags":["import"],"summary":"Whether the AI document importer is available","responses":{"200":{"description":"Availability of the AI importer for this org and plan.","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/import/analyze":{"post":{"tags":["import"],"summary":"Split a document into candidate entries (AI)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportAnalyze"}}}},"responses":{"200":{"description":"Candidate entries for review.","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/ImportCandidate"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/import/csv":{"post":{"tags":["import"],"summary":"Parse CSV text into candidate entries","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportCsv"}}}},"responses":{"200":{"description":"Parsed candidates plus per-row errors.","content":{"application/json":{"schema":{"type":"object","properties":{"candidates":{"type":"array","items":{"$ref":"#/components/schemas/ImportCandidate"}},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"message":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/import/bulk":{"post":{"tags":["import"],"summary":"Bulk-create confirmed candidate entries","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportBulk"}}}},"responses":{"201":{"description":"Created entry ids plus per-item errors.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"array","items":{"type":"string"}},"errors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}