--- title: "Read the collection's documents into its classes and relationships" method: POST path: "/api/v0/knowledge-bases/{kb_id}/graph/reading" tags: ["Knowledge Base Graph"] --- # Read the collection's documents into its classes and relationships `POST /api/v0/knowledge-bases/{kb_id}/graph/reading` ## Request - Base URL: `https://api.outerport.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.outerport.com/api/v0/knowledge-bases/{kb_id}/graph/reading` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Queues one run over the collection's documents: one model reading per email conversation (its emails and their attachments, read as one) and per other document (per part, for a long one) whose text, or whose collection's classes, relationships or their email roles, changed since it was last read. For each class and relationship given an email role in the class editor, each conversation, email, sender and attachment and the links between them are written from the headers, and the reading points at them. The run writes instances of the collection's own domain classes, each grounded in the documents it was read from, and the relationships between them that the collection defines. Two instances of one class with the same name are one entity, including one a person created. On a collection that subscribes the support-knowledge package, the same run writes the package's cases, emails, people and attachments from the headers, reads each conversation for its problems, causes and resolutions (in the same model call as the collection's own classes where both need it), then writes the similarity between problems and the FAQs. Returns immediately with a job status to poll. Nothing a person wrote to is deleted, a name or attribute a person edited keeps the person's value, and an entity or link a person deleted is not written again. Stopping the run still writes every document it read in full. Refused with 400 when the collection defines no domain class and does not subscribe the support package, its email roles do not fit together, or it holds no documents; with 403 when it subscribes the support package and the caller's tier does not include it; and with 409 while another reading of the collection is in progress. ## Path parameters - `kb_id` string, uuid, required ## Request body - CollectionReadRequest: What one reading covers. Every field has a default, so an empty body is valid. - `reread` boolean: Read everything again, including what matches its last reading. - `limit` integer, nullable: Read at most this many of the documents and conversations that need reading; the next run continues with the rest. ## Response `202` Successful Response - CollectionReadResponse: The accepted run, not its result. Poll ``job_status_id``. - `job_status_id` string, uuid, required ## Other responses - `422`: Validation Error ## Changes - **2026-10-22** `762a02693cbb`: 1 info - endpoint added [Operation history](https://skmtc.dev/outerport/apis/outerport-api/changes/api/v0/knowledge-bases/:kb_id/graph/reading/post.md) --- [API](https://skmtc.dev/outerport/apis/outerport-api.md) - [All operations](https://skmtc.dev/outerport/apis/outerport-api/llms.txt) - [OpenAPI document](https://skmtc.dev/outerport/apis/outerport-api/revisions/08b5bf6f7f18?raw)