> ## 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.
# List Corpora
> Retrieve every corpus you own along with indexing metadata.
## Overview
List all corpora owned by the authenticated user with pagination support. This endpoint is safe for multi-tenant environments as it automatically filters results to only show corpora you created.
**Use this for**: Building corpus selection UI, monitoring corpus status, tracking indexing progress, auditing corpus inventory.
## Authentication
Requires valid JWT token or session authentication. Anonymous requests return `401 Unauthorized`.
## Query Parameters
Page number for pagination. Use with `page_size` to navigate through large corpus lists.
Number of corpora per page. Maximum value depends on server configuration (typically 100).
**Recommendation**: Use smaller page sizes (20-50) for better performance.
## Example request
```bash theme={null}
curl -X GET https://{your-host}/api/corpora/ \
-H "Authorization: Bearer $SOAR_LABS_TOKEN" \
-G --data-urlencode "page=1" --data-urlencode "page_size=10"
```
## Example response
```json theme={null}
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "8d0f0a5d-4b5e-4c09-9db6-0e9d2aa8a9fd",
"created_at": "2024-09-01T10:05:03.291Z",
"updated_at": "2024-09-01T10:06:42.102Z",
"corpora_name": "support_playbooks",
"description": "Playbooks for tier-1 engineers",
"size_on_disk": 10485760.0,
"index_location": "qdrant_free_collection",
"is_published": false,
"index_type": "VSI",
"indexing_status": "IND",
"creator": "eb81c1d5-78fe-4f35-b58e-0ff6a3ad5d12"
}
]
}
```
## Response Structure
Total number of corpora owned by you (across all pages).
URL to fetch the next page of results. `null` if on the last page.
URL to fetch the previous page of results. `null` if on the first page.
Array of corpus objects. See [Create Corpus](/api-reference/corpora/create) for full field documentation.
**Key fields:**
* `id` - Corpus UUID
* `corpora_name` - Normalized name (lowercase snake\_case)
* `indexing_status` - Current status (`PND`, `PRS`, `IND`, `ERR`)
* `size_on_disk` - Storage size in bytes
* `index_type` - Indexing strategy (`VSI`, `SMI`, `DSI`)
* `is_published` - Public visibility flag
## Best Practices
Handle large corpus lists efficiently:
```python theme={null}
def get_all_corpora(base_url, token):
all_corpora = []
page = 1
while True:
response = requests.get(
f"{base_url}/api/corpora/",
headers={"Authorization": f"Bearer {token}"},
params={"page": page, "page_size": 50}
)
data = response.json()
all_corpora.extend(data["results"])
if not data["next"]:
break
page += 1
return all_corpora
```
Client-side filtering for specific corpus states:
```python theme={null}
# Get only fully indexed corpora
response = requests.get(f"{base_url}/api/corpora/", headers=headers)
indexed_corpora = [
c for c in response.json()["results"]
if c["indexing_status"] == "IND"
]
# Get corpora with errors
error_corpora = [
c for c in response.json()["results"]
if c["indexing_status"] == "ERR"
]
```
Use normalized names consistently:
```python theme={null}
# ✓ Correct - Use the normalized name from API
display_name = corpus["corpora_name"]
# ✗ Incorrect - Don't try to transform yourself
display_name = user_input.lower().replace(" ", "_")
```
**Why**: The server may apply additional normalization beyond simple lowercasing and underscore replacement.
Before creating a new corpus, validate the name:
```bash theme={null}
curl -X GET "https://{your-host}/api/check_corpora_name/?corpora_name=my_corpus" \
-H "Authorization: Bearer $SOAR_LABS_TOKEN"
```
Returns `200 OK` if name is available, `400 Bad Request` if already taken.
## Monitoring & Analytics
Use this endpoint to build monitoring dashboards that track:
* Total corpus count over time
* Storage usage (`size_on_disk` aggregation)
* Indexing pipeline health (`indexing_status` distribution)
* Published vs private corpus ratio
## Client examples
```python theme={null}
import os
import requests
BASE_URL = "https://your-soar-instance.com"
TOKEN = os.environ["SOAR_LABS_TOKEN"]
response = requests.get(
f"{BASE_URL}/api/corpora/",
headers={"Authorization": f"Bearer {TOKEN}"},
params={"page": 1, "page_size": 10},
timeout=30,
)
response.raise_for_status()
corpora = response.json()["results"]
```
```ts theme={null}
const BASE_URL = "https://your-soar-instance.com";
const token = process.env.SOAR_LABS_TOKEN!;
async function listCorpora() {
const url = new URL("/api/corpora/", BASE_URL);
url.searchParams.set("page", "1");
url.searchParams.set("page_size", "10");
const response = await fetch(url, {
headers: {
Authorization: `Bearer ${token}`,
},
});
if (!response.ok) {
throw new Error(`Listing corpora failed: ${response.status}`);
}
return response.json();
}
```
```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 client = HttpClient.newHttpClient();
var uri = URI.create(BASE_URL + "/api/corpora/?page=1&page_size=10");
var request = HttpRequest.newBuilder(uri)
.header("Authorization", "Bearer " + token)
.GET()
.build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) {
throw new RuntimeException("Listing corpora failed: " + response.statusCode());
}
var body = response.body(); // parse with your preferred JSON library
```
## OpenAPI
````yaml GET /api/corpora/
openapi: 3.0.3
info:
title: Soar Labs API - Insider Dev preview
version: 0.1.0
description: Soar Labs Advanced RAG platform
servers: []
security: []
paths:
/api/corpora/:
get:
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_list
parameters:
- name: page
required: false
in: query
description: A page number within the paginated result set.
schema:
type: integer
- name: page_size
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCorporaList'
description: ''
security:
- jwtHeaderAuth: []
- jwtCookieAuth: []
- cookieAuth: []
- basicAuth: []
components:
schemas:
PaginatedCorporaList:
type: object
required:
- count
- results
properties:
count:
type: integer
example: 123
next:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=4
previous:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=2
results:
type: array
items:
$ref: '#/components/schemas/Corpora'
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
````