> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Model

> Understanding how Raydocs resources relate to each other

Raydocs organizes document extraction into a clear hierarchy. Understanding this structure helps you design effective workflows and use the API efficiently.

## Resource Hierarchy

```mermaid theme={null}
graph TD
    W[Workspace] --> T[Extraction Template]
    T --> S[Extraction Session]
    S --> D[Document]
    S --> R[Extraction Result]
    D --> C[Chunk]
```

## Core Resources

<AccordionGroup>
  <Accordion title="Workspace" icon="building">
    **The top-level organizational container.**

    Workspaces group templates, sessions, and team members together. Each workspace has its own set of users with specific roles (admin, user, readonly).

    | Field  | Description       |
    | ------ | ----------------- |
    | `id`   | Unique identifier |
    | `name` | Display name      |
    | `icon` | Emoji or icon     |

    **One workspace can contain:** Multiple templates, unlimited sessions, multiple team members
  </Accordion>

  <Accordion title="Extraction Template" icon="file-code">
    **Defines what data to extract.**

    Templates contain the JSON schema that specifies which fields to extract from documents. Each template belongs to one workspace and can be used across many sessions.

    | Field          | Description                  |
    | -------------- | ---------------------------- |
    | `id`           | UUID identifier              |
    | `name`         | Template name                |
    | `description`  | Optional description         |
    | `schema_json`  | Extraction schema definition |
    | `settings`     | Parsing configuration        |
    | `workspace_id` | Parent workspace             |

    **Key relationships:**

    * Belongs to one Workspace
    * Used by many Sessions
  </Accordion>

  <Accordion title="Extraction Session" icon="play">
    **An individual extraction job.**

    Sessions are where actual extraction happens. You upload documents to a session, run the extraction, and retrieve results. Each session uses one template.

    | Field                    | Description                            |
    | ------------------------ | -------------------------------------- |
    | `id`                     | UUID identifier                        |
    | `name`                   | Session name                           |
    | `extraction_template_id` | Template to use                        |
    | `status`                 | pending, processing, completed, failed |

    **Key relationships:**

    * Uses one Template
    * Contains many Documents
    * Produces Results
  </Accordion>

  <Accordion title="Document" icon="file-pdf">
    **A source file for extraction.**

    Documents are PDFs, images, or other files uploaded to a session. After upload, documents are automatically parsed into chunks for extraction.

    | Field       | Description                      |
    | ----------- | -------------------------------- |
    | `id`        | UUID identifier                  |
    | `filename`  | Original filename                |
    | `mime_type` | File type                        |
    | `size`      | Size in bytes                    |
    | `status`    | pending, parsing, parsed, failed |

    **Key relationships:**

    * Belongs to one Session
    * Contains many Chunks (after parsing)
  </Accordion>

  <Accordion title="Chunk" icon="puzzle-piece">
    **A parsed segment of a document.**

    When documents are processed, they're split into chunks — meaningful segments of text with page references. The AI uses these chunks to find and extract data.

    | Field         | Description             |
    | ------------- | ----------------------- |
    | `id`          | UUID identifier         |
    | `content`     | Text content            |
    | `page_number` | Source page             |
    | `chunk_index` | Order within document   |
    | `metadata`    | Additional parsing info |

    **Key relationships:**

    * Belongs to one Document
    * Referenced in extraction Results
  </Accordion>

  <Accordion title="Extraction Result" icon="check-circle">
    **The extracted data output.**

    Results contain the structured data extracted from session documents according to the template schema. Each result includes the extracted values and optionally AI reasoning traces.

    | Field       | Description                            |
    | ----------- | -------------------------------------- |
    | `id`        | UUID identifier                        |
    | `status`    | pending, processing, completed, failed |
    | `data`      | Extracted values                       |
    | `reasoning` | AI reasoning (if enabled)              |

    **Key relationships:**

    * Belongs to one Session
    * References source Documents/Chunks
  </Accordion>
</AccordionGroup>

## Typical Workflow

<Steps>
  <Step title="Create a Workspace">
    Set up a workspace for your project or team. Invite collaborators if needed.
  </Step>

  <Step title="Design an Extraction Template">
    Define what data you want to extract using the JSON schema format. Include field definitions, search queries, and extraction prompts.

    <Tip>
      See the [Extraction Schema Guide](/guides/extraction-schema) for detailed schema documentation.
    </Tip>
  </Step>

  <Step title="Create an Extraction Session">
    For each batch of documents you want to process, create a session linked to your template.
  </Step>

  <Step title="Upload Documents">
    Add your source documents (PDFs, images, etc.) to the session. Documents are automatically parsed into chunks.
  </Step>

  <Step title="Run Extraction">
    Execute the extraction. The AI searches relevant chunks and extracts data according to your schema.
  </Step>

  <Step title="Retrieve Results">
    Access the structured extraction results via API or export to Excel/CSV.
  </Step>
</Steps>

## Resource Limits

| Resource                | Limit         |
| ----------------------- | ------------- |
| Workspaces per user     | Based on plan |
| Templates per workspace | Unlimited     |
| Sessions per template   | Unlimited     |
| Documents per session   | 100           |
| File size               | 50 MB         |

<Note>
  Limits may vary based on your subscription plan. Contact support for enterprise limits.
</Note>

## API Navigation

<CardGroup cols={2}>
  <Card title="Workspaces API" icon="building" href="/api-reference/workspaces/list-workspaces">
    Manage workspaces and team members.
  </Card>

  <Card title="Templates API" icon="file-code" href="/api-reference/templates/list-templates">
    Create and configure extraction schemas.
  </Card>

  <Card title="Sessions API" icon="play" href="/api-reference/sessions/create-session">
    Run extraction jobs on documents.
  </Card>

  <Card title="Results API" icon="check-circle" href="/api-reference/results/list-results">
    Access extracted data and exports.
  </Card>
</CardGroup>