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

# Partially Update Corpus

> Change an individual corpus field without resending the full payload.

## Overview

Update specific corpus fields without affecting others. This is the recommended approach for incremental changes like toggling visibility, updating descriptions, or modifying individual settings.

<Info>
  **Recommended for most updates**: Only send the fields you want to change. All other fields remain unchanged.
</Info>

<Tip>
  Perfect for single-field updates like toggling `is_published` or updating descriptions without risk of resetting other values.
</Tip>

## Authentication

Requires valid JWT token or session authentication. You must own the target corpus.

## Path Parameters

<ParamField path="id" type="UUID" required>
  Corpus identifier to partially update.

  **Example**: `8d0f0a5d-4b5e-4c09-9db6-0e9d2aa8a9fd`
</ParamField>

## Request Body

Send only the fields you want to modify:

<ParamField body="corpora_name" type="string">
  New corpus name (will be normalized to lowercase with underscores). Must be unique.

  **Validation**: Server automatically normalizes the name.
</ParamField>

<ParamField body="description" type="string">
  Updated description of the corpus purpose.
</ParamField>

<ParamField body="is_published" type="boolean">
  Toggle public visibility. `true` makes the corpus discoverable by other users.

  **Common use case**: Publishing/unpublishing corpora for access control.
</ParamField>

<ParamField body="index_type" type="string">
  Change indexing strategy: `VSI`, `SMI`, or `DSI`

  <Warning>
    Changing this triggers background re-indexing of all resources.
  </Warning>
</ParamField>

<ParamField body="indexing_status" type="string">
  Manual status override (advanced use only).

  <Note>
    Normally managed automatically by the system. Only modify if coordinating with backend operators.
  </Note>
</ParamField>

## Example request

```bash theme={null}
curl -X PATCH https://{your-host}/api/corpora/8d0f0a5d-4b5e-4c09-9db6-0e9d2aa8a9fd/ \
  -H "Authorization: Bearer $SOAR_LABS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Add tier-2 troubleshooting flows",
    "is_published": false
  }'
```

## Example response

```json theme={null}
{
  "id": "8d0f0a5d-4b5e-4c09-9db6-0e9d2aa8a9fd",
  "description": "Add tier-2 troubleshooting flows",
  "is_published": false,
  "corpora_name": "support_playbooks",
  "index_type": "VSI",
  "indexing_status": "IND",
  "size_on_disk": 4194304.0,
  "index_location": "qdrant_free_collection",
  "created_at": "2024-09-01T10:05:03.291Z",
  "updated_at": "2024-09-02T07:23:18.081Z",
  "creator": "eb81c1d5-78fe-4b35-b58e-0ff6a3ad5d12"
}
```

## Response Structure

Returns the complete corpus object with your changes applied:

<ResponseField name="id" type="UUID">
  Unchanged corpus identifier.
</ResponseField>

<ResponseField name="updated_at" type="timestamp">
  Updated to reflect when the change was made.
</ResponseField>

<ResponseField name="corpora_name" type="string">
  Corpus name (updated if you changed it, otherwise unchanged).
</ResponseField>

<ResponseField name="description" type="string">
  Updated description if modified, otherwise original value.
</ResponseField>

<ResponseField name="is_published" type="boolean">
  Updated visibility flag if modified, otherwise original value.
</ResponseField>

<ResponseField name="index_type" type="string">
  Updated indexing strategy if modified. If changed, `indexing_status` may switch to `PRS`.
</ResponseField>

<ResponseField name="indexing_status" type="string">
  May change to `PRS` if re-indexing was triggered by `index_type` modification.
</ResponseField>

<ResponseField name="size_on_disk" type="float">
  Unchanged storage size.
</ResponseField>

<ResponseField name="index_location" type="string">
  Unchanged vector database collection.
</ResponseField>

<ResponseField name="created_at" type="timestamp">
  Unchanged original creation time.
</ResponseField>

<ResponseField name="creator" type="UUID">
  Unchanged corpus owner (read-only).
</ResponseField>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Toggle Publication Status" icon="eye">
    The most common PATCH operation - make a corpus public or private:

    ```python theme={null}
    # Publish a corpus
    requests.patch(
        f"{base_url}/api/corpora/{corpus_id}/",
        headers=headers,
        json={"is_published": True}
    )

    # Unpublish for maintenance
    requests.patch(
        f"{base_url}/api/corpora/{corpus_id}/",
        headers=headers,
        json={"is_published": False}
    )
    ```

    **Use case**: Temporarily hiding a corpus during updates or making it available to other users.
  </Accordion>

  <Accordion title="Update Description Only" icon="pen">
    Modify the description without affecting any other fields:

    ```python theme={null}
    requests.patch(
        f"{base_url}/api/corpora/{corpus_id}/",
        headers=headers,
        json={"description": "Updated with Q4 2024 product documentation"}
    )
    ```

    **Safe**: No risk of accidentally changing name, visibility, or index type.
  </Accordion>

  <Accordion title="Batch Status Updates" icon="list-check">
    Update multiple corpora efficiently:

    ```python theme={null}
    corpus_ids = ["id1", "id2", "id3"]

    # Publish all corpora
    for corpus_id in corpus_ids:
        try:
            requests.patch(
                f"{base_url}/api/corpora/{corpus_id}/",
                headers=headers,
                json={"is_published": True}
            )
            print(f"Published {corpus_id}")
        except Exception as e:
            print(f"Failed to publish {corpus_id}: {e}")
    ```
  </Accordion>

  <Accordion title="Safe Index Type Migration" icon="arrows-spin">
    Change index strategy while preserving all other settings:

    ```python theme={null}
    # Get current corpus
    corpus = requests.get(
        f"{base_url}/api/corpora/{corpus_id}/",
        headers=headers
    ).json()

    print(f"Current index type: {corpus['index_type']}")

    # Update only the index type
    updated = requests.patch(
        f"{base_url}/api/corpora/{corpus_id}/",
        headers=headers,
        json={"index_type": "SMI"}  # Switch to Summary Index
    ).json()

    # Wait for re-indexing
    if updated["indexing_status"] == "PRS":
        print("Re-indexing started. Monitor status...")
    ```

    **Note**: All other fields (name, description, visibility) remain unchanged.
  </Accordion>

  <Accordion title="Conditional Updates" icon="code-branch">
    Update only if conditions are met:

    ```python theme={null}
    # Get current state
    corpus = requests.get(
        f"{base_url}/api/corpora/{corpus_id}/",
        headers=headers
    ).json()

    # Only publish if indexing is complete
    if corpus["indexing_status"] == "IND":
        requests.patch(
            f"{base_url}/api/corpora/{corpus_id}/",
            headers=headers,
            json={"is_published": True}
        )
        print("Corpus published")
    else:
        print(f"Corpus not ready (status: {corpus['indexing_status']})")
    ```
  </Accordion>
</AccordionGroup>

<Note>
  **Validation**: Name uniqueness and `index_type` enum validation still apply. Invalid values return `400 Bad Request`.
</Note>

<Tip>
  **Best Practice**: Always use PATCH for single-field updates rather than PUT to avoid accidentally resetting fields to defaults.
</Tip>

## Client examples

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    BASE_URL = "https://your-soar-instance.com"
    TOKEN = os.environ["SOAR_LABS_TOKEN"]
    CORPUS_ID = "8d0f0a5d-4b5e-4c09-9db6-0e9d2aa8a9fd"

    response = requests.patch(
        f"{BASE_URL}/api/corpora/{CORPUS_ID}/",
        headers={
            "Authorization": f"Bearer {TOKEN}",
            "Content-Type": "application/json",
        },
        json={"is_published": False, "description": "Add tier-2 troubleshooting flows"},
        timeout=30,
    )
    response.raise_for_status()
    patched = response.json()
    ```
  </Tab>

  <Tab title="TypeScript / JavaScript">
    ```ts theme={null}
    const BASE_URL = "https://your-soar-instance.com";
    const token = process.env.SOAR_LABS_TOKEN!;

    async function patchCorpus(corpusId: string) {
      const response = await fetch(`${BASE_URL}/api/corpora/${corpusId}/`, {
        method: "PATCH",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${token}`,
        },
        body: JSON.stringify({
          description: "Add tier-2 troubleshooting flows",
          is_published: false,
        }),
      });

      if (!response.ok) {
        throw new Error(`Patch corpus failed: ${response.status}`);
      }

      return response.json();
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import java.net.URI;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;

    var BASE_URL = "https://your-soar-instance.com";
    var token = System.getenv("SOAR_LABS_TOKEN");
    var corpusId = "8d0f0a5d-4b5e-4c09-9db6-0e9d2aa8a9fd";

    var json = "{" +
        "\"description\":\"Add tier-2 troubleshooting flows\"," +
        "\"is_published\":false" +
    "}";

    var request = HttpRequest.newBuilder(URI.create(BASE_URL + "/api/corpora/" + corpusId + "/"))
        .header("Authorization", "Bearer " + token)
        .header("Content-Type", "application/json")
        .method("PATCH", HttpRequest.BodyPublishers.ofString(json))
        .build();

    var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

    if (response.statusCode() >= 400) {
        throw new RuntimeException("Patch corpus failed: " + response.statusCode());
    }

    var body = response.body();
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml PATCH /api/corpora/{id}/
openapi: 3.0.3
info:
  title: Soar Labs API - Insider Dev preview
  version: 0.1.0
  description: <b>Soar Labs Advanced RAG platform</b>
servers: []
security: []
paths:
  /api/corpora/{id}/:
    patch:
      tags:
        - Corpora
      description: >-
        Corpora creation API using Django Rest Framework.


        This viewset provides CRUD operations for Corpora objects.


        ### Responses


        - **201 Created**: Returned on successful creation of a Corpora.

        - **400 Bad Request**: Returned if the request data is invalid.

        - **401 Unauthorized**: Returned if the user is not authenticated.

        - **403 Forbidden**: Returned if the user is not authorized to perform
        the operation.

        - **404 Not Found**: Returned if the requested Corpora does not exist.


        ### Permissions

        - `IsAuthenticated`: Users must be authenticated to access this
        endpoint.
      operationId: api_corpora_partial_update
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          description: A UUID string identifying this Corpora.
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedCorpora'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedCorpora'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedCorpora'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corpora'
          description: ''
      security:
        - jwtHeaderAuth: []
        - jwtCookieAuth: []
        - cookieAuth: []
        - basicAuth: []
components:
  schemas:
    PatchedCorpora:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the organization was created
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: Last updated time
        corpora_name:
          type: string
          description: Name of the corpora
          maxLength: 100
        description:
          type: string
          nullable: true
          description: Description of the corpora
        size_on_disk:
          type: number
          format: double
          readOnly: true
          title: Size
          description: Size of the corpora on disk (in bytes)
        index_location:
          type: string
          readOnly: true
          nullable: true
          title: Location of Index
          description: Location of the index on Remote Storage
        is_published:
          type: boolean
          title: Publishing Status
          description: Is the corpora Visible to all users?
        index_type:
          allOf:
            - $ref: '#/components/schemas/IndexTypeEnum'
          description: |-
            Type of index to be used for the corpora

            * `VSI` - VectorStoreIndex
            * `SMI` - SummaryIndex
            * `DSI` - DocumentSummaryIndex
        indexing_status:
          allOf:
            - $ref: '#/components/schemas/IndexingStatusEnum'
          title: Index Processing Status
          description: |-
            Status of the corpora processing

            * `PND` - Pending
            * `IQE` - In Queue
            * `PRS` - Processing
            * `DEX` - Data Extracted Successfully
            * `DER` - Data Extraction Error
            * `IND` - Indexed
            * `CMP` - Completed
            * `ERR` - Error
        creator:
          type: string
          format: uuid
          readOnly: true
    Corpora:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the organization was created
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: Last updated time
        corpora_name:
          type: string
          description: Name of the corpora
          maxLength: 100
        description:
          type: string
          nullable: true
          description: Description of the corpora
        size_on_disk:
          type: number
          format: double
          readOnly: true
          title: Size
          description: Size of the corpora on disk (in bytes)
        index_location:
          type: string
          readOnly: true
          nullable: true
          title: Location of Index
          description: Location of the index on Remote Storage
        is_published:
          type: boolean
          title: Publishing Status
          description: Is the corpora Visible to all users?
        index_type:
          allOf:
            - $ref: '#/components/schemas/IndexTypeEnum'
          description: |-
            Type of index to be used for the corpora

            * `VSI` - VectorStoreIndex
            * `SMI` - SummaryIndex
            * `DSI` - DocumentSummaryIndex
        indexing_status:
          allOf:
            - $ref: '#/components/schemas/IndexingStatusEnum'
          title: Index Processing Status
          description: |-
            Status of the corpora processing

            * `PND` - Pending
            * `IQE` - In Queue
            * `PRS` - Processing
            * `DEX` - Data Extracted Successfully
            * `DER` - Data Extraction Error
            * `IND` - Indexed
            * `CMP` - Completed
            * `ERR` - Error
        creator:
          type: string
          format: uuid
          readOnly: true
      required:
        - corpora_name
        - created_at
        - creator
        - id
        - index_location
        - size_on_disk
        - updated_at
    IndexTypeEnum:
      enum:
        - VSI
        - SMI
        - DSI
      type: string
      description: |-
        * `VSI` - VectorStoreIndex
        * `SMI` - SummaryIndex
        * `DSI` - DocumentSummaryIndex
    IndexingStatusEnum:
      enum:
        - PND
        - IQE
        - PRS
        - DEX
        - DER
        - IND
        - CMP
        - ERR
      type: string
      description: |-
        * `PND` - Pending
        * `IQE` - In Queue
        * `PRS` - Processing
        * `DEX` - Data Extracted Successfully
        * `DER` - Data Extraction Error
        * `IND` - Indexed
        * `CMP` - Completed
        * `ERR` - Error
  securitySchemes:
    jwtHeaderAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    jwtCookieAuth:
      type: apiKey
      in: cookie
      name: soar-app-auth
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
    basicAuth:
      type: http
      scheme: basic

````