Partially Update Corpus

JavaScript

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({corpora_name: '<string>', description: '<string>', is_published: true})
};

fetch('https://api.example.com/api/corpora/{id}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request PATCH \
  --url https://api.example.com/api/corpora/{id}/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "corpora_name": "<string>",
  "description": "<string>",
  "is_published": true
}
'

import requests

url = "https://api.example.com/api/corpora/{id}/"

payload = {
    "corpora_name": "<string>",
    "description": "<string>",
    "is_published": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.patch("https://api.example.com/api/corpora/{id}/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"corpora_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"is_published\": true\n}")
  .asString();

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "corpora_name": "<string>",
  "size_on_disk": 123,
  "index_location": "<string>",
  "creator": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "description": "<string>",
  "is_published": true
}

PATCH

api

corpora

{id}

JavaScript

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({corpora_name: '<string>', description: '<string>', is_published: true})
};

fetch('https://api.example.com/api/corpora/{id}/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request PATCH \
  --url https://api.example.com/api/corpora/{id}/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "corpora_name": "<string>",
  "description": "<string>",
  "is_published": true
}
'

import requests

url = "https://api.example.com/api/corpora/{id}/"

payload = {
    "corpora_name": "<string>",
    "description": "<string>",
    "is_published": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.patch("https://api.example.com/api/corpora/{id}/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"corpora_name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"is_published\": true\n}")
  .asString();

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "corpora_name": "<string>",
  "size_on_disk": 123,
  "index_location": "<string>",
  "creator": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "description": "<string>",
  "is_published": true
}

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.

Recommended for most updates: Only send the fields you want to change. All other fields remain unchanged.

Perfect for single-field updates like toggling is_published or updating descriptions without risk of resetting other values.

Authentication

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

Path Parameters

UUID

required

Corpus identifier to partially update.Example: 8d0f0a5d-4b5e-4c09-9db6-0e9d2aa8a9fd

Request Body

Send only the fields you want to modify:

string

New corpus name (will be normalized to lowercase with underscores). Must be unique.Validation: Server automatically normalizes the name.

string

Updated description of the corpus purpose.

boolean

Toggle public visibility. true makes the corpus discoverable by other users.Common use case: Publishing/unpublishing corpora for access control.

string

Change indexing strategy: VSI, SMI, or DSI

Changing this triggers background re-indexing of all resources.

string

Manual status override (advanced use only).

Normally managed automatically by the system. Only modify if coordinating with backend operators.

Example request

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

{
  "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:

UUID

Unchanged corpus identifier.

timestamp

Updated to reflect when the change was made.

string

Corpus name (updated if you changed it, otherwise unchanged).

string

Updated description if modified, otherwise original value.

boolean

Updated visibility flag if modified, otherwise original value.

string

Updated indexing strategy if modified. If changed, indexing_status may switch to PRS.

string

May change to PRS if re-indexing was triggered by index_type modification.

float

Unchanged storage size.

string

Unchanged vector database collection.

timestamp

Unchanged original creation time.

UUID

Unchanged corpus owner (read-only).

Common Use Cases

Toggle Publication Status

The most common PATCH operation - make a corpus public or private:

# 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.

Update Description Only

Modify the description without affecting any other fields:

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.

Batch Status Updates

Update multiple corpora efficiently:

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}")

Safe Index Type Migration

Change index strategy while preserving all other settings:

# 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.

Conditional Updates

Update only if conditions are met:

# 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']})")

Validation: Name uniqueness and index_type enum validation still apply. Invalid values return 400 Bad Request.

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

Client examples

Python
TypeScript / JavaScript
Java

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()

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();
}

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();

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string<uuid>

required

A UUID string identifying this Corpora.

Body

corpora_name

string

Name of the corpora

Maximum string length: 100

description

string | null

Description of the corpora

is_published

boolean

Is the corpora Visible to all users?

index_type

enum<string>

Type of index to be used for the corpora

VSI - VectorStoreIndex
SMI - SummaryIndex
DSI - DocumentSummaryIndex

Available options:

VSI,

SMI,

DSI

indexing_status

enum<string>

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

Available options:

PND,

IQE,

PRS,

DEX,

DER,

IND,

CMP,

ERR

Response

200 - application/json

string<uuid>

required

read-only

created_at

string<date-time>

required

read-only

The date and time the organization was created

updated_at

string<date-time>

required

read-only

Last updated time

corpora_name

string

required

Name of the corpora

Maximum string length: 100

size_on_disk

number<double>

required

read-only

Size of the corpora on disk (in bytes)

index_location

string | null

required

read-only

Location of the index on Remote Storage

creator

string<uuid>

required

read-only

description

string | null

Description of the corpora

is_published

boolean

Is the corpora Visible to all users?

index_type

enum<string>

Type of index to be used for the corpora

VSI - VectorStoreIndex
SMI - SummaryIndex
DSI - DocumentSummaryIndex

Available options:

VSI,

SMI,

DSI

indexing_status

enum<string>

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

Available options:

PND,

IQE,

PRS,

DEX,

DER,

IND,

CMP,

ERR

Update Delete

Getting Started

Corpus Management

Query and Retrieve

Resources

Overview

Authentication

Path Parameters

Request Body

Example request

Example response

Response Structure

Common Use Cases

Client examples

Authorizations

Path Parameters

Body

Response

​Overview

​Authentication

​Path Parameters

​Request Body

​Example request

​Example response

​Response Structure

​Common Use Cases

​Client examples

Authorizations

Path Parameters

Body

Response

Overview

Authentication

Path Parameters

Request Body

Example request

Example response

Response Structure

Common Use Cases

Client examples