UpdateFaster global search
captain

Blog

Copy Collections

Lewis Lien PolanskyCEO & Co-Founder

You can now copy collections in Captain. One API call duplicates the documents, chunks, embeddings, and custom metadata under a new collection name, reusing the index you already built.

5 min read

Fig. 00 · one API call duplicates documents, chunks, embeddings and metadata

You can now copy collections in Captain. One API call duplicates the documents, chunks, embeddings, and custom metadata under a new collection name, reusing the index you already built.

One call, one copy

copy-collection.sh
curl -X POST https://api.captain.dev/v2/collections/shipping_manuals/copy \
  -H "Authorization: Bearer $CAPTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_name": "shipping_manuals_staging"}'
Fig. 01 · the whole operation, in one request

Copied collections are fully independent. Writes and deletes stay scoped to the collection they were issued against.

Why we built it

Three requests kept coming up:

One collection per customer.

If you run retrieval for many end clients, each client's data belongs in its own collection: separate indexes and separate deletes. Standing up client number forty used to mean re-indexing a shared corpus for the fortieth time. Now you can index the base corpus once, then easily copy it per client.

Staging copies.

Sometimes a collection needs to branch. Production stays on the settings your users depend on while a copy absorbs the change you're not sure about yet: a different parsing configuration, a new chunk relationship setup, a different PII masking policy. Test against the copy with real data, and when the branch proves out, cut over. When it drifts too far, you can delete it and copy again.

Experiments.

Snapshot a collection before a risky change. If the experiment fails, delete the copy and the original is untouched.

What it used to cost

Before this endpoint, duplicating a collection meant re-indexing it from the source files: paying indexing credits on every document again, then waiting on the job queue, sometimes for hours, before the duplicate was usable.

A copy is a flat 10 credits, billed once the copy succeeds. Because the vectors are copied rather than rebuilt, the operation completes in about a second. Both numbers hold at any collection size.

Here it is against a real collection:

request.sh
curl -X POST https://api.captain.dev/v2/collections/blog_demo_shipping_manuals/copy \
  -H "Authorization: Bearer $CAPTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_name": "blog_demo_shipping_manuals_staging"}'
Fig. 02 · the request
200 OK · 1.28s
{
  "success": true,
  "message": "Copied 'blog_demo_shipping_manuals' to 'blog_demo_shipping_manuals_staging' (6 documents)",
  "source_collection": "blog_demo_shipping_manuals",
  "collection_name": "blog_demo_shipping_manuals_staging",
  "collection_id": "01a01749-7d73-7401-89ec-8261383d631c",
  "documents_copied": 6,
  "files_copied": 6,
  "namespaces_copied": 1
}
Fig. 03 · the response, 1.28 seconds later

Details

  • POST /v2/collections/{collection_name}/copy with a target_name in the body.
  • The target name must be unused in the collection's environment; a taken name returns a 409.
  • Copies land in the same environment as the source and behave like any other collection: query them, index into them, delete them.

Reference documentation for the endpoint is at docs.captain.dev/reference/collections/copy.

Lewis Lien Polansky

CEO & Co-Founder · Captain

Lewis is co-founder and CEO of Captain, building self-tuning file search for AI agents.