Update Corpus

JavaScript

const options = {
  method: 'PUT',
  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 PUT \
  --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.put(url, json=payload, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.put("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
}

PUT

api

corpora

{id}

JavaScript

const options = {
  method: 'PUT',
  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 PUT \
  --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.put(url, json=payload, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.put("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

Replace all mutable corpus fields in a single request. This is a full replacement operation - any field not provided will be reset to its default value.

Use with caution: Omitted fields reset to defaults. For single-field updates, use PATCH /api/corpora/{id}/ instead.

Best for: Renaming a corpus along with other metadata changes, or when you need to reset all fields to known values.

Authentication

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

Path Parameters

UUID

required

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

Request Body

string

required

Corpus name (will be normalized to lowercase with underscores). Must be unique across your corpora.Validation: The server automatically converts to lowercase and replaces spaces with underscores.Uniqueness: Fails with 400 Bad Request if another of your corpora has the same normalized name.

string

Human-readable description of the corpus purpose.Default: Empty string if omitted.

boolean

default:"false"

Public visibility flag. Set to true to make the corpus discoverable by other users.Default: false (private) if omitted.

string

default:"VSI"

Indexing strategy for the corpus:

VSI - Vector Store Index (best for semantic search)
SMI - Summary Index
DSI - Document Summary Index

Warning: Changing this triggers asynchronous re-indexing of all resources.

string

Current processing state. Advanced use only - normally managed automatically by the system.Valid values: PND, PRS, IND, ERR

Manually setting this does NOT trigger indexing jobs. Leave this field alone unless coordinating with backend operators.

Example request

curl -X PUT https://{your-host}/api/corpora/8d0f0a5d-4b5e-4c09-9db6-0e9d2aa8a9fd/ \
  -H "Authorization: Bearer $SOAR_LABS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "corpora_name": "support_playbooks",
    "description": "Updated description",
    "is_published": true,
    "index_type": "VSI",
    "indexing_status": "IND"
  }'

Example response

{
  "id": "8d0f0a5d-4b5e-4c09-9db6-0e9d2aa8a9fd",
  "created_at": "2024-09-01T10:05:03.291Z",
  "updated_at": "2024-09-02T07:12:44.914Z",
  "corpora_name": "support_playbooks",
  "description": "Updated description",
  "size_on_disk": 4194304.0,
  "index_location": "qdrant_free_collection",
  "is_published": true,
  "index_type": "VSI",
  "indexing_status": "IND",
  "creator": "eb81c1d5-78fe-4f35-b58e-0ff6a3ad5d12"
}

Response Structure

UUID

Unchanged corpus identifier.

timestamp

Original creation timestamp (never changes).

timestamp

Updated to current time when the request succeeds.

string

Normalized corpus name after update.

string

Updated description (or empty string if omitted in request).

boolean

Updated visibility flag (or false if omitted).

string

Updated indexing strategy (or VSI if omitted).

string

Processing state. May show PRS if index_type was changed and re-indexing started.

float

Unchanged storage size.

string

Vector database collection identifier (unchanged).

UUID

Unchanged corpus owner ID (read-only field).

Best Practices

PUT vs PATCH - When to Use Each

Use PUT when:

Renaming a corpus along with other changes
You want to explicitly reset fields to defaults
You have a complete corpus object to replace

Use PATCH when:

Updating a single field (e.g., toggling is_published)
Making incremental changes without affecting other fields
You don’t want to risk accidentally resetting fields

Example - Wrong approach:

# ❌ BAD: Using PUT to only change description
# This resets is_published to false!
requests.put(
    f"{base_url}/api/corpora/{corpus_id}/",
    json={"corpora_name": "my_corpus", "description": "New description"}
)

Example - Correct approach:

# ✅ GOOD: Use PATCH for single field updates
requests.patch(
    f"{base_url}/api/corpora/{corpus_id}/",
    json={"description": "New description"}
)

Handling Name Collisions

The server enforces name uniqueness across your corpora:

try:
    response = requests.put(
        f"{base_url}/api/corpora/{corpus_id}/",
        headers=headers,
        json={
            "corpora_name": "duplicate_name",
            "description": "Test",
            "is_published": False,
            "index_type": "VSI"
        }
    )
    response.raise_for_status()
except requests.HTTPError as e:
    if e.response.status_code == 400:
        error = e.response.json()
        if "corpora_name" in error:
            print("Name collision - choose a different name")

Tip: Use GET /api/check_corpora_name/?corpora_name=new_name before attempting the update.

Index Type Migration

Changing index_type triggers background re-indexing:

# Update to different index type
response = requests.put(
    f"{base_url}/api/corpora/{corpus_id}/",
    headers=headers,
    json={
        "corpora_name": "support_playbooks",
        "description": "Switching to summary index",
        "index_type": "SMI",  # Changed from VSI
        "is_published": False
    }
)

# Monitor re-indexing progress
while True:
    corpus = requests.get(
        f"{base_url}/api/corpora/{corpus_id}/",
        headers=headers
    ).json()

    if corpus["indexing_status"] == "IND":
        print("Re-indexing complete")
        break
    elif corpus["indexing_status"] == "ERR":
        print("Re-indexing failed")
        break

    time.sleep(10)

Performance impact: Large corpora may take minutes to re-index. Plan migrations during low-traffic periods.

Atomic Updates with Verification

Ensure updates succeed and verify the result:

# Get current state
original = requests.get(
    f"{base_url}/api/corpora/{corpus_id}/",
    headers=headers
).json()

try:
    # Attempt full update
    updated = requests.put(
        f"{base_url}/api/corpora/{corpus_id}/",
        headers=headers,
        json={
            "corpora_name": "renamed_corpus",
            "description": "Updated description",
            "is_published": True,
            "index_type": original["index_type"]  # Keep same type
        }
    ).json()

    # Verify critical fields
    assert updated["corpora_name"] == "renamed_corpus"
    assert updated["is_published"] == True
    print("Update verified successfully")

except Exception as e:
    print(f"Update failed: {e}")
    # Original corpus state is unchanged on failure

Error Handling: 400 Bad Request indicates either a name collision or attempt to modify read-only fields like creator, id, or created_at.

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"

payload = {
    "corpora_name": "support_playbooks",
    "description": "Updated description",
    "is_published": True,
    "index_type": "VSI",
}

response = requests.put(
    f"{BASE_URL}/api/corpora/{CORPUS_ID}/",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
updated = response.json()

const BASE_URL = "https://your-soar-instance.com";
const token = process.env.SOAR_LABS_TOKEN!;

async function updateCorpus(corpusId: string) {
  const response = await fetch(`${BASE_URL}/api/corpora/${corpusId}/`, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      corpora_name: "support_playbooks",
      description: "Updated description",
      is_published: true,
      index_type: "VSI",
    }),
  });

  if (!response.ok) {
    throw new Error(`Update 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 = "{" +
    "\"corpora_name\":\"support_playbooks\"," +
    "\"description\":\"Updated description\"," +
    "\"is_published\":true," +
    "\"index_type\":\"VSI\"" +
"}";

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

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

if (response.statusCode() >= 400) {
    throw new RuntimeException("Update 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

required

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

Retrieve Partial Update

Getting Started

Corpus Management

Query and Retrieve

Resources

Overview

Authentication

Path Parameters

Request Body

Example request

Example response

Response Structure

Best Practices

Client examples

Authorizations

Path Parameters

Body

Response

​Overview

​Authentication

​Path Parameters

​Request Body

​Example request

​Example response

​Response Structure

​Best Practices

​Client examples

Authorizations

Path Parameters

Body

Response

Overview

Authentication

Path Parameters

Request Body

Example request

Example response

Response Structure

Best Practices

Client examples