{"openapi":"3.1.0","info":{"title":"Skimle API","version":"1.0.0","description":"Public REST API for reading and writing project data on Skimle.\n\n## Authentication\n\nEvery request needs an `Authorization: Bearer <api-key>` header.\nAPI keys are project-scoped — one key gives access to exactly one\nproject — and come in two flavours marked by their final character:\n\n- `skm_…r` — **read** key (only `/api/skimle-read`)\n- `skm_…e` — **edit** key (both `/api/skimle-read` and\n  `/api/skimle-write`)\n\nCreate keys at\n[https://skimle.com/home/api-keys](https://skimle.com/home/api-keys).\nThe full key value is shown **once** at creation — copy it then.\nSkimle only stores the hash, so a key that wasn't saved at\ncreation is gone for good.\n\n## Rate limits\n\n- `/api/skimle-read` — **60 requests / minute / project**\n- `/api/skimle-write` — **30 requests / minute / project**\n\n## Short IDs\n\nMost ID fields accept three formats interchangeably:\n\n- UUID — `e07ca2f6-…`\n- Counter-based short ID — `D3k` (document), `I205y` (insight)\n- Prefixed hash — `C1a2b3c4` (category), `T5d6e7f8` (tag)\n\nResponses always return prefixed hashes / counter IDs — never raw UUIDs."},"servers":[{"url":"https://skimle.com","description":"Default (uses the host that served this docs page)"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Read","description":"Query project data — projects, documents, insights, categories, tags, notes, memos, metadata, plus semantic search and document chunk reading."},{"name":"Write","description":"Mutate project data — create / update / delete insights, manage categories and tags, create notes, batch-add insights with quote verification."}],"paths":{"/api/skimle-read":{"post":{"tags":["Read"],"summary":"Read project data","description":"Single dispatcher endpoint. The request body picks an action via the `action` discriminator. Each action has its own body shape — see the `oneOf` below.","operationId":"skimleRead","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"action":{"type":"string","const":"get_project"}},"required":["action"],"additionalProperties":false,"title":"get_project"},{"type":"object","properties":{"action":{"type":"string","const":"get_documents"},"id":{"type":"string","maxLength":200},"filters":{"type":"object","properties":{"tags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"categories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"metadata":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","maxLength":200},"value":{"type":"string","maxLength":1000}},"required":["field","value"],"additionalProperties":false}},"documentIds":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},"excludeCategories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"excludeTags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}}},"additionalProperties":false}},"required":["action"],"additionalProperties":false,"title":"get_documents"},{"type":"object","properties":{"action":{"type":"string","const":"get_insights"},"id":{"type":"string","maxLength":200},"ids":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","maxLength":200}},"filters":{"type":"object","properties":{"tags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"categories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"metadata":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","maxLength":200},"value":{"type":"string","maxLength":1000}},"required":["field","value"],"additionalProperties":false}},"documentIds":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},"excludeCategories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"excludeTags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}}},"additionalProperties":false}},"required":["action"],"additionalProperties":false,"title":"get_insights"},{"type":"object","properties":{"action":{"type":"string","const":"get_categories"},"id":{"type":"string","maxLength":200},"filters":{"type":"object","properties":{"tags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"categories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"metadata":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","maxLength":200},"value":{"type":"string","maxLength":1000}},"required":["field","value"],"additionalProperties":false}},"documentIds":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},"excludeCategories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"excludeTags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}}},"additionalProperties":false}},"required":["action"],"additionalProperties":false,"title":"get_categories"},{"type":"object","properties":{"action":{"type":"string","const":"get_memos"},"id":{"type":"string","maxLength":200}},"required":["action"],"additionalProperties":false,"title":"get_memos"},{"type":"object","properties":{"action":{"type":"string","const":"get_tags"}},"required":["action"],"additionalProperties":false,"title":"get_tags"},{"type":"object","properties":{"action":{"type":"string","const":"get_notes"},"filters":{"type":"object","properties":{"tags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"categories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"metadata":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","maxLength":200},"value":{"type":"string","maxLength":1000}},"required":["field","value"],"additionalProperties":false}},"documentIds":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},"excludeCategories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"excludeTags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}}},"additionalProperties":false}},"required":["action"],"additionalProperties":false,"title":"get_notes"},{"type":"object","properties":{"action":{"type":"string","const":"get_metadata"}},"required":["action"],"additionalProperties":false,"title":"get_metadata"},{"type":"object","properties":{"action":{"type":"string","const":"search"},"query":{"type":"string","minLength":1,"maxLength":8000},"queries":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":8000}},"topK":{"type":"integer","minimum":1,"maximum":50},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"onlyInsights":{"type":"boolean"},"filters":{"type":"object","properties":{"tags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"categories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"metadata":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","maxLength":200},"value":{"type":"string","maxLength":1000}},"required":["field","value"],"additionalProperties":false}},"documentIds":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},"excludeCategories":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"excludeTags":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}}},"additionalProperties":false}},"required":["action"],"additionalProperties":false,"title":"search"},{"type":"object","properties":{"action":{"type":"string","const":"read_document"},"documentId":{"type":"string","maxLength":200},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"type":"integer","minimum":1,"maximum":30}},"required":["action","documentId"],"additionalProperties":false,"title":"read_document"},{"type":"object","properties":{"action":{"type":"string","const":"find_entities"},"entity":{"type":"string","maxLength":500}},"required":["action"],"additionalProperties":false,"title":"find_entities"},{"type":"object","properties":{"action":{"type":"string","const":"analyze"},"type":{"type":"string","enum":["metadata_distribution","temporal"]},"categoryIds":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"categoryNames":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}}},"required":["action","type"],"additionalProperties":false,"title":"analyze"},{"type":"object","properties":{"action":{"type":"string","const":"verify_context"},"type":{"type":"string","enum":["documents","insights","all"]},"from":{"type":"integer","minimum":1,"maximum":9007199254740991},"to":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["action"],"additionalProperties":false,"title":"verify_context"}]},"examples":{"get-categories-tree":{"summary":"List the category tree","value":{"action":"get_categories"}},"get-insights-filtered":{"summary":"List insights in a category, excluding those tagged \"Resolved\"","value":{"action":"get_insights","filters":{"categories":["Onboarding"],"excludeTags":["Resolved"]}}},"search":{"summary":"Semantic search","value":{"action":"search","query":"pricing pain points","topK":10}},"read-document":{"summary":"Read a document in pages of chunks","value":{"action":"read_document","documentId":"D3k","offset":0,"limit":20}}}}}},"responses":{"200":{"description":"Action-specific result. Shape varies per `action` — see the action descriptions.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Validation error (invalid JSON or schema mismatch).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — for example, a read-only key was used on /skimle-write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Read: 60 req/min/project. Write: 30 req/min/project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/skimle-write":{"post":{"tags":["Write"],"summary":"Mutate project data","description":"Single dispatcher endpoint. The request body picks an action via the `action` discriminator. Each action has its own body shape — see the `oneOf` below. Requires an edit-scoped API key (suffix `e`).","operationId":"skimleWrite","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"action":{"type":"string","const":"manage_insights"},"operation":{"type":"string","enum":["create","update","delete"]},"id":{"type":"string","maxLength":200},"insightIds":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":200}},"documentId":{"type":"string","maxLength":200},"text":{"type":"string","minLength":1,"maxLength":2000},"description":{"type":"string","maxLength":4000},"quotes":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":4000}},"categories":{}},"required":["action","operation","categories"],"additionalProperties":false,"title":"manage_insights"},{"type":"object","properties":{"action":{"type":"string","const":"manage_categories"},"operation":{"type":"string","enum":["create","update","delete","merge"]},"id":{"type":"string","maxLength":200},"text":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","maxLength":4000},"parentId":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"categoryName":{"type":"string","maxLength":500},"deleteIfNotEmpty":{"type":"boolean"},"categoryIds":{"minItems":2,"maxItems":100,"type":"array","items":{"type":"string","maxLength":200}},"newName":{"type":"string","minLength":1,"maxLength":500}},"required":["action","operation"],"additionalProperties":false,"title":"manage_categories"},{"type":"object","properties":{"action":{"type":"string","const":"categorize_insights"},"operation":{"type":"string","enum":["assign","move","remove"]},"insightIds":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","maxLength":200}},"categoryId":{"type":"string","maxLength":200}},"required":["action","operation","insightIds","categoryId"],"additionalProperties":false,"title":"categorize_insights"},{"type":"object","properties":{"action":{"type":"string","const":"manage_tags"},"operation":{"type":"string","enum":["create","update","delete","add_targets","remove_targets"]},"id":{"type":"string","maxLength":200},"text":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","maxLength":4000},"color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"documentIds":{"maxItems":1000,"type":"array","items":{"type":"string","maxLength":200}},"insightIds":{"maxItems":1000,"type":"array","items":{"type":"string","maxLength":200}},"categoryIds":{"maxItems":1000,"type":"array","items":{"type":"string","maxLength":200}}},"required":["action","operation"],"additionalProperties":false,"title":"manage_tags"},{"type":"object","properties":{"action":{"type":"string","const":"create_note"},"targetType":{"type":"string","enum":["document","documentInsight","insightCategory"]},"targetId":{"type":"string","maxLength":200},"text":{"type":"string","minLength":1,"maxLength":10000}},"required":["action","targetType","targetId","text"],"additionalProperties":false,"title":"create_note"},{"type":"object","properties":{"action":{"type":"string","const":"manage_metadata_fields"},"operation":{"type":"string","enum":["create","update","delete"]},"id":{"type":"string","maxLength":200},"text":{"type":"string","minLength":1,"maxLength":500},"shortName":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":4000},"parentId":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"valueType":{"type":"string","enum":["authors","date","language","number","organization"]},"fieldName":{"type":"string","maxLength":500},"deleteIfNotEmpty":{"type":"boolean"}},"required":["action","operation"],"additionalProperties":false,"title":"manage_metadata_fields"},{"type":"object","properties":{"action":{"type":"string","const":"set_metadata_values"},"documentId":{"type":"string","maxLength":200},"values":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"fieldId":{"type":"string","maxLength":200},"text":{"type":"string","minLength":1,"maxLength":2000},"shortName":{"type":"string","minLength":1,"maxLength":200},"value":{}},"required":["fieldId","text"],"additionalProperties":false}}},"required":["action","documentId","values"],"additionalProperties":false,"title":"set_metadata_values"},{"type":"object","properties":{"action":{"type":"string","const":"start_analysis"},"type":{"type":"string","enum":["inductive","summaries","metadata_summaries"]},"strictMode":{"type":"boolean"},"analysisGranularity":{"type":"string","enum":["default","inclusive","overview"]}},"required":["action","type"],"additionalProperties":false,"title":"start_analysis"}]},"examples":{"create-insight":{"summary":"Create an insight on one document in a subcategory","value":{"action":"manage_insights","operation":"create","documentId":"D3k","text":"Cost is a barrier to adoption","quotes":["it's just too expensive","we couldn't afford it"],"description":"Multiple respondents cited cost as the main blocker.","categories":["C1a2b3c4"]}},"categorize-assign":{"summary":"Assign several insights into an additional category","value":{"action":"categorize_insights","operation":"assign","insightIds":["I205y","I340z"],"categoryId":"C1a2b3c4"}},"manage-categories-merge":{"summary":"Merge two categories into a new one","value":{"action":"manage_categories","operation":"merge","categoryIds":["C1a2b3c4","Cabcd1234"],"newName":"Pricing & Affordability"}},"tags-add":{"summary":"Apply a tag to several insights","value":{"action":"manage_tags","operation":"add_targets","id":"T5d6e7f8","insightIds":["I205y","I340z","I420a"]}},"delete-insights-bulk":{"summary":"Delete a list of insights in one call","value":{"action":"manage_insights","operation":"delete","insightIds":["I205y","I340z"]}}}}}},"responses":{"200":{"description":"Action-specific result. Shape varies per `action` — see the action descriptions.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Validation error (invalid JSON or schema mismatch).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden — for example, a read-only key was used on /skimle-write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Read: 60 req/min/project. Write: 30 req/min/project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"skm_…r (read) or skm_…e (edit)"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable message."},"details":{"description":"Optional structured detail — present on 400 responses with the per-field validation errors."}},"additionalProperties":false}}}}