> ## Documentation Index > Fetch the complete documentation index at: https://docs.clarifeye.ai/llms.txt > Use this file to discover all available pages before exploring further. # Read imported object rows > Read-only, paginated retrieval of the rows imported into one version of an imported object extractor. Imported objects are written directly by the import task, not by extraction-flow hydration, so they have no `HydrationComputation` records and cannot be read through `tables/{table_id}/extractor-table-retrieval/`. Rows are matched on the `extractor_version_id` column of the extractor's imported-objects table. **What it returns:** rows of the extractor's imported-objects table (`id`, `provided_id`, `document_id`, `json_object`, `extractor_version_id`, `deleted`) for the given version. By default soft-deleted rows (`deleted IS NOT NULL`) are left out. When the extractor has no imported-objects table yet (nothing imported), the response is an empty page. POST is used only because the request carries a filter and column body: this endpoint never writes. **Filtering:** Keys are column names, optionally suffixed with a lookup: `__in` or `__iin` (case-insensitive) for a list or comma-separated string, `__gt`, `__gte`, `__lt`, `__lte`, `__isnull`, and `__icontains`. A bare `__icontains` key searches every text, JSON and UUID column, or only those listed under `searchColumns`. A plain key is an equality match. Keys naming a column that does not exist are silently ignored. Any `extractor_version_id` filter is overridden by the request's `extractor_version_id`, and `processing_options` is stripped. **Permissions:** `technical_setup:read` on the project. ## OpenAPI ````yaml /api-reference/openapi-full.yaml post /projects/{project_id}/imported-object-extractors/{extractor_id}/retrieve-data/ openapi: 3.0.3 info: title: Clarifeye Platform API — Full API Documentation description: > Complete REST API reference for the Clarifeye Platform. Documents every endpoint exposed by the platform — the public surface plus the advanced surface: pipeline customization (extraction flows, pipeline runs, warehouse tables, document tag/metadata configuration), the pre-MCP AI surface (agent settings, playground conversations, conversation-scoped feedback views, notifications), and the impersonation header. New AI integrations should consume knowledge via MCP rather than the conversation/agent-settings endpoints documented here. ## Authentication All endpoints require authentication. Include the Authorization header in every request using either format: - `Authorization: Token ` - `Authorization: Bearer ` ## Service accounts and API keys Integrations authenticate with an **API key** of a **service account**: - `Authorization: Bearer ` (keys start with `cfk_`) A service account is an ordinary member (role `member`) of one organization that cannot log in. Organization admins create it and mint its keys on the organization's *Service accounts* page (`/organizations/{id}/service-accounts/`, `/organization-api-keys/`), and give it access to knowledge stores with ordinary store permissions. A key is valid on every endpoint and acts as its service account: it reaches exactly the stores, with exactly the rights, the account was given. An account can hold several keys (each with its own name, optional expiry and revocation), so a key can be rotated without changing identity. A refused key answers **403** with one of: `Invalid API key.`, `API key revoked.`, `API key expired.`, `API key disabled.` (the service account is disabled). Any valid key may also call `POST /organizations/{id}/provision-user/` and `POST /organizations/{id}/deprovision-user/` for its own organization (the `{id}` in the path must be the key's organization). The email domains these may pre-create accounts for are configured by Clarifeye on the organization (`allowed_provisioning_domains`). ## Impersonation Certain endpoints support user impersonation for creating or listing data on behalf of other users. This is useful for integrating external systems that need to attribute actions to specific users. **Header:** `X-Impersonate-Email` **Required Permission:** `CAN_IMPERSONATE_OTHER_USERS` (for a person, contact Clarifeye to enable it; org admins grant it to a service account on the organization's Service accounts page) **Behavior:** - If the header is provided and the impersonator has the required permission, the action is performed as the target user - If the target user is not found, the request proceeds as the original authenticated user - If the target user does not have access to the project, the request proceeds as the original authenticated user - If the impersonator lacks the `CAN_IMPERSONATE_OTHER_USERS` permission, the header is ignored **With an API key** the request fails instead (**403**) whenever impersonation cannot happen: missing permission, unknown target, target without access to the store, target that is itself a service account, or an endpoint outside a store. A key never silently acts as its own service account when impersonation was asked for. version: 1.0.0 contact: name: Clarifeye Support servers: - url: https://eu.app.clarifeye.ai/api/v1 description: EU - url: https://us.app.clarifeye.ai/api/v1 description: US security: - BearerAuth: [] - TokenAuth: [] tags: - name: Users description: Manage users within a project - name: Invitations description: Manage project invitations - name: Documents description: Manage documents within a project - name: Agent Settings description: Manage AI agent configurations - name: Conversations description: Create and interact with AI-powered conversations - name: Interviews description: Assign and review structured interview conversations - name: Meetings description: >- Meetings Clara attends as a bot (Recall.ai) — live transcript, live insights, recording, and calendar scheduling (CLA-1843). Store admins only. - name: Feedback description: >- Submit and review feedback — standalone (content-only), agent-submitted (MCP), or linked to a conversation message - name: Tools description: Execute configured AI tools with custom parameters - name: Tables description: Perform CRUD operations on warehouse tables - name: Notifications description: Manage project-scoped notifications for users - name: Extraction Flows description: >- Manage extraction flows (auto-sync DAGs) — list, run, inspect statistics, update, and publish - name: Object Extractors description: | Extract structured data (instances of a Pydantic model) from chunks or blocks of documents. Update auto-creates a new `ObjectExtractorVersion` when version-bearing fields change. - name: Tag Extractors description: | Apply hierarchical metadata tags to chunks or documents using an LLM. Update auto-creates a new `TagExtractorVersion` when version-bearing fields change. - name: Chunks Extractors description: | Segment parsed documents into chunks for downstream processing. Update auto-creates a new `ChunksExtractorVersion` when version-bearing fields change. - name: Parsing Extractors description: | Convert source documents to text blocks via the parsing pipeline. Update auto-creates a new `ParsingExtractorVersion` when version-bearing fields change. - name: Document Filter Extractors description: | Restrict a downstream pipeline branch to documents matching a filter. Update auto-creates a new version when the filter changes. - name: Chunk Tag Filter Extractors description: | Restrict a downstream pipeline branch to chunks carrying specific tags. Update auto-creates a new version when the filter changes. - name: Document Tag Extractors description: | Apply a flat set of metadata tags to each document. Update auto-creates a new version when version-bearing fields change. - name: Tag Alerts Extractors description: | Run LLM-based alerts over already-extracted tag rows. Update auto-creates a new version when version-bearing fields change. - name: Object Alerts Extractors description: > Run LLM-based alerts over already-extracted object rows. Update auto-creates a new version when version-bearing fields change. - name: Imported Object Extractors description: | Hold objects imported from an external system (rather than extracted by an LLM). Useful for hydrating the warehouse with data produced outside the platform. - name: Pipeline Runs description: >- Inspect pipeline runs queued by extraction flows or other pipeline triggers — list runs and fetch the details/status of a single run - name: User Provisioning description: > Pre-create and de-provision org users via an org-scoped API key (`Authorization: Bearer `). The organization is resolved from the key. - name: Organization API Keys description: | Management of org-scoped provisioning API keys. Org admins can mint, list, retrieve, update, reveal, and revoke their own org's keys. - name: Design System Templates description: Reference/example files attached to a design template. - name: Artifacts description: | Knowledge-store artifact catalog — list artifacts, create/edit custom artifacts, manage scope membership, read and publish versions, configure the store map, and export/import the whole catalog. For type-aware reads and edits of artifact content, prefer the `read-write-*-artifact` tool endpoints. paths: /projects/{project_id}/imported-object-extractors/{extractor_id}/retrieve-data/: post: tags: - Imported Object Extractors summary: Read imported object rows description: | Read-only, paginated retrieval of the rows imported into one version of an imported object extractor. Imported objects are written directly by the import task, not by extraction-flow hydration, so they have no `HydrationComputation` records and cannot be read through `tables/{table_id}/extractor-table-retrieval/`. Rows are matched on the `extractor_version_id` column of the extractor's imported-objects table. **What it returns:** rows of the extractor's imported-objects table (`id`, `provided_id`, `document_id`, `json_object`, `extractor_version_id`, `deleted`) for the given version. By default soft-deleted rows (`deleted IS NOT NULL`) are left out. When the extractor has no imported-objects table yet (nothing imported), the response is an empty page. POST is used only because the request carries a filter and column body: this endpoint never writes. **Filtering:** Keys are column names, optionally suffixed with a lookup: `__in` or `__iin` (case-insensitive) for a list or comma-separated string, `__gt`, `__gte`, `__lt`, `__lte`, `__isnull`, and `__icontains`. A bare `__icontains` key searches every text, JSON and UUID column, or only those listed under `searchColumns`. A plain key is an equality match. Keys naming a column that does not exist are silently ignored. Any `extractor_version_id` filter is overridden by the request's `extractor_version_id`, and `processing_options` is stripped. **Permissions:** `technical_setup:read` on the project. operationId: retrieveImportedObjectExtractorData parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/ExtractorId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImportedObjectRetrievalRequest' examples: read_version_page: summary: First page of a version's rows value: extractor_version_id: 5b0f1a2c-7d3e-4f60-9a1b-2c3d4e5f6a7b limit: 100 offset: 0 read_for_document: summary: Rows attached to one document value: extractor_version_id: 5b0f1a2c-7d3e-4f60-9a1b-2c3d4e5f6a7b filters: document_id: 82c71787-37e9-42ca-a995-982e2ed53169 columns: - id - provided_id - document_id - json_object limit: 500 offset: 0 read_by_provided_ids: summary: Look up rows by the ids given in the import file value: extractor_version_id: 5b0f1a2c-7d3e-4f60-9a1b-2c3d4e5f6a7b filters: provided_id__in: - CTR-0012 - CTR-0047 search_text: summary: Free-text search across columns description: | A bare `__icontains` key matches rows where any text, JSON or UUID column contains the value (case-insensitive). value: extractor_version_id: 5b0f1a2c-7d3e-4f60-9a1b-2c3d4e5f6a7b filters: __icontains: renewal limit: 50 offset: 0 read_include_deleted: summary: Include soft-deleted rows value: extractor_version_id: 5b0f1a2c-7d3e-4f60-9a1b-2c3d4e5f6a7b include_deleted_rows: true responses: '200': description: Rows retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ExtractorTableRetrievalResponse' '400': description: '`extractor_version_id` is missing.' content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: | The extractor does not exist in this project, or `extractor_version_id` is not a version of this extractor. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: The table query failed. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: ProjectId: name: project_id in: path required: true description: UUID of the project schema: type: string format: uuid ExtractorId: name: extractor_id in: path required: true description: UUID of the extractor schema: type: string format: uuid schemas: ImportedObjectRetrievalRequest: type: object required: - extractor_version_id properties: extractor_version_id: type: string format: uuid description: UUID of the imported object extractor version whose rows to return. filters: type: object description: | Column-level filters. Keys are column names with optional lookups (`__in`, `__iin`, `__gt`, `__gte`, `__lt`, `__lte`, `__isnull`, `__icontains`). Unknown columns are ignored. Sending `deleted__isnull` overrides the default soft-delete filter. additionalProperties: true example: document_id: 82c71787-37e9-42ca-a995-982e2ed53169 columns: type: array nullable: true description: | Column names to return in each row. Omit (or send `null` / `[]`) to return every column. items: type: string example: - id - provided_id - document_id - json_object include_deleted_rows: type: boolean default: false description: When `true`, also return rows whose `deleted` flag is set. limit: type: integer default: 100 description: Maximum number of rows to return. offset: type: integer default: 0 description: Number of rows to skip for pagination. ExtractorTableRetrievalResponse: type: object description: | Wrapper around the paginated list of rows produced by the requested `ExtractorVersion`. properties: result: type: object properties: results: type: array description: The rows matching the request. items: type: object additionalProperties: true total: type: integer description: Total number of matching rows (ignoring `limit` / `offset`). limit: type: integer description: Echo of the `limit` used to compute this page. offset: type: integer description: Echo of the `offset` used to compute this page. has_next: type: boolean description: True when `offset + limit < total`. has_previous: type: boolean description: True when `offset > 0`. Error: type: object properties: error: type: string description: Error message example: error: User not found responses: Unauthorized: description: Unauthorized - missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Authentication credentials were not provided. Forbidden: description: Forbidden - insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: You do not have permission to perform this action. securitySchemes: BearerAuth: type: http scheme: bearer description: > Use `Authorization: Bearer `. The token is either a user token / OAuth access token, or a service-account API key (`cfk_...`). A key is valid on every endpoint and acts as its service account, an organization member with per-store permissions. Refused keys answer 403 with `Invalid API key.`, `API key revoked.`, `API key expired.` or `API key disabled.`. TokenAuth: type: apiKey in: header name: Authorization description: 'Use Authorization: Token ' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.