Collection API

Collection routes are split into public collections (platform-managed) and private collections (user-owned).

API call order

1. Call GET /collections/public to get valid public collection names.
2. Optionally call POST /collections to create a private collection.
3. Use these names/IDs in message generation and document upload routes.

Shared request setup is documented once in API index.

List public collections

GET /collections/public?page=1&limit=20

List public collections with pagination.

Combines platform-curated public collections and environment-specific public collections, then paginates the combined list.

Parameters:

Name	Type	Description	Default
pagination	Pagination	Pagination parameters.	Depends()

Returns:

Type	Description
PaginatedResponse[Collection]	Paginated list of public collections.

Usage

resp = requests.get(
    f"{BASE_URL}/collections/public",
    params={"page": 1, "limit": 20},
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
public_collections = resp.json()["data"]
print([c["name"] for c in public_collections])

Explanation

Returns selectable public collections. These names are required by generation endpoints.

Notes

• Pass returned name values to public_collections in message/generate requests.

List my private collections

GET /collections?page=1&limit=20

List collections owned by the current user.

Parameters:

Name	Type	Description	Default
request	Pagination	Pagination parameters.	Depends()
request_user	User	Authenticated user injected by dependency.	Depends(get_current_user)

Returns:

Type	Description
PaginatedResponse[Collection]	Paginated list of user collections.

Usage

resp = requests.get(
    f"{BASE_URL}/collections",
    params={"page": 1, "limit": 20},
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
my_collections = resp.json()["data"]
print([(c["id"], c["name"]) for c in my_collections])

Explanation

Lists private collections owned by the authenticated user.

Notes

• Use returned IDs with document endpoints.

Create private collection

POST /collections

Create a private collection and provision its backing vector index (Qdrant).

The new collection is private to its creator. The MongoDB collection ID is used as the Qdrant collection name.

Parameters:

Name	Type	Description	Default
request	CollectionRequest	New collection parameters.	required
requesting_user	User	Authenticated user injected by dependency.	Depends(get_current_user)

Returns:

Type	Description
Collection	Created collection.

Raises:

Type	Description
HTTPException	500 if vector collection creation fails or on server errors.

Usage

resp = requests.post(
    f"{BASE_URL}/collections",
    json={
        "name": "eo-missions-notes",
        "description": "Internal notes for Sentinel and Copernicus docs",
        "embeddings_model": "Qwen/Qwen3-Embedding-4B",
    },
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
collection = resp.json()
COLLECTION_ID = collection["id"]
print(collection)

Explanation

Creates a user-owned collection for document ingestion and private retrieval.

Notes

• embeddings_model is optional; default is server-defined.

Get one collection

GET /collections/{collection_id}

Get a collection by id with document and vector counts.

Parameters:

Name	Type	Description	Default
collection_id	str	Target collection identifier.	required
requesting_user	User	Authenticated user injected by dependency.	Depends(get_current_user)

Returns:

Type	Description
dict	Collection data including documents_count and points_count.

Raises:

Type	Description
HTTPException	404 if collection is not found.
HTTPException	403 if the collection is owned by another user.

Usage

resp = requests.get(
    f"{BASE_URL}/collections/{COLLECTION_ID}",
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Explanation

Returns collection metadata and counters such as document/vector totals.

Notes

• Useful to confirm ingestion completed successfully.

Rename collection

PATCH /collections/{collection_id}

Update a collection's mutable fields.

Parameters:

Name	Type	Description	Default
request	CollectionUpdate	Update payload (e.g., name).	required
collection_id	str	Collection identifier.	required
requesting_user	User	Authenticated user injected by dependency.	Depends(get_current_user)

Returns:

Type	Description
Collection	Updated collection.

Raises:

Type	Description
HTTPException	404 if not found; 403 if update is forbidden; 500 for server errors.

Usage

resp = requests.patch(
    f"{BASE_URL}/collections/{COLLECTION_ID}",
    json={"name": "eo-missions-notes-v2"},
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Explanation

Updates mutable collection metadata.

Notes

• Keep references in client code synchronized after rename.

Delete collection

DELETE /collections/{collection_id}

Delete a collection and its related resources.

Deletes documents in the collection, attempts to remove the vector index, and finally deletes the collection record.

Parameters:

Name	Type	Description	Default
collection_id	str	Collection identifier.	required
requesting_user	User	Authenticated user injected by dependency.	Depends(get_current_user)

Returns:

Type	Description
dict	Confirmation message.

Raises:

Type	Description
HTTPException	404 if not found; 403 if deletion is forbidden; 500 for server errors.

Usage

resp = requests.delete(
    f"{BASE_URL}/collections/{COLLECTION_ID}",
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Explanation

Deletes the collection and removes related stored data.

Notes

• Destructive operation; confirm ownership and usage before calling.

Full API reference

For exhaustive schema details, use Swagger API.