Copy Collection

POST

https://api.captain.dev/v2/collections/:collection_name/copy

POST

/v2/collections/:collection_name/copy

1 import requests
2 
3 BASE_URL = "https://api.captain.dev"
4 API_KEY = "your_api_key"
5 COLLECTION_NAME = "my_documents"
6 
7 headers = {
8     "Authorization": f"Bearer {API_KEY}",
9     "Content-Type": "application/json"
10 }
11 
12 response = requests.post(
13     f"{BASE_URL}/v2/collections/{COLLECTION_NAME}/copy",
14     headers=headers,
15     json={"target_name": "my_documents_v2"},
16     timeout=120.0
17 )
18 
19 if response.status_code == 200:
20     data = response.json()
21     print(f"Created {data['collection_name']} ({data['documents_copied']} documents)")
22 elif response.status_code == 409:
23     print("That name is taken. Choose a different target_name.")
24 else:
25     print(f"Error {response.status_code}: {response.text}")

1 {
2   "success": true,
3   "message": "Copied 'my_documents' to 'my_documents_v2' (142 documents)",
4   "source_collection": "my_documents",
5   "collection_name": "my_documents_v2",
6   "database_id": "01931f4e-8c2a-7c31-9f5e-2b7a1d3e4f60",
7   "documents_copied": 142,
8   "namespaces_copied": 2,
9   "files_copied": 142,
10   "relations_copied": 356,
11   "chunk_metadata_copied": 89,
12   "relations_unresolved": 0
13 }

Clone metadata, documents, and vectors under a new name. Instant regardless of size.

Path parameters

collection_namestringRequired

Request

This endpoint expects an object.

target_namestringRequired

Name for the copy. Must be unique within the organization and environment. Same rules as creating a collection: 3-63 characters, alphanumeric start and end, letters, numbers, hyphens and underscores only.

include_graphbooleanOptionalDefaults to true

Copy the collection’s chunk relations and chunk metadata along with its documents and vectors. Defaults to true so a copy is a faithful original; set false to copy documents and vectors only.

Response

Successful Response

successboolean

messagestring

source_collectionstring

Name of the collection copied from.

collection_namestring

Name of the new copy.

database_idstring

ID of the new copy.

documents_copiedinteger

Number of documents cloned.

namespaces_copiedinteger

Number of Turbopuffer namespaces copied (text plus any media).

files_copiedintegerOptionalDefaults to 0

Number of files cloned.

relations_copiedintegerOptionalDefaults to 0

Number of chunk relations cloned. Counts ROWS, not distinct edges: duplicate (source, target, type) triples in the source are reproduced faithfully.

chunk_metadata_copiedintegerOptionalDefaults to 0

Number of chunk metadata rows cloned.

relations_unresolvedintegerOptionalDefaults to 0

Relations copied whose target document could not be remapped into the new collection, so their target_document_id is null. Usually these are edges already broken in the source (the target document was deleted, or the id never matched a document); if the source was being indexed while the copy ran, a freshly created edge can also land here. The copy reproduces the edge rather than writing a pointer that resolves to nothing.

Errors

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error