> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Create Collection

PUT https://api.captain.dev/v2/collections/{collection_name}
Content-Type: application/json

Create a collection by name. The request is idempotent for an existing collection.

Reference: https://docs.captain.dev/reference/collections/create

## Request

### Path parameters

- `collection_name` (string, required)

### Body (application/json)

This endpoint expects a CollectionCreateRequest.

- `description` (string, optional, nullable)
- `metadata` (CollectionCreateRequestMetadata, optional, nullable)

## Response

### 201

Successful Response

- `collection_id` (string, required)
- `collection_name` (string, required)
- `organization_id` (string, required)
- `created_at` (string, optional, nullable)
- `description` (string, optional, nullable)
- `metadata` (CollectionResponseMetadata, optional, nullable)

## Types

### CollectionCreateRequestMetadata

### CollectionResponseMetadata

## Examples

**Request**

```json
{
  "description": "A collection of research documents"
}
```

**Response**

```json
{
  "collection_id": "019abc12-3456-7890-abcd-ef1234567890",
  "collection_name": "my_documents",
  "organization_id": "org_019abc12",
  "description": "A collection of research documents",
  "metadata": {}
}
```

**SDK Code**

```python Python REST
import requests
import json

BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
COLLECTION_NAME = "my_documents"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.put(
    f"{BASE_URL}/v2/collections/{COLLECTION_NAME}",
    headers=headers,
    json={},
    timeout=30.0
)

if response.status_code in [200, 201]:
    print("Collection created successfully!")
    print(json.dumps(response.json(), indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)
```

```typescript TypeScript REST
const BASE_URL = "https://api.captain.dev";
const API_KEY = "your_api_key";
const COLLECTION_NAME = "my_documents";

const response = await fetch(
    `${BASE_URL}/v2/collections/${COLLECTION_NAME}`,
    {
        method: "PUT",
        headers: {
            "Authorization": `Bearer ${API_KEY}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify({})
    }
);

if (response.ok) {
    const data = await response.json();
    console.log("Collection created!", JSON.stringify(data, null, 2));
} else {
    console.error(`Error: ${response.status}`);
}
```

> Captain is a fully managed API for deterministic file search over unstructured data. Connect cloud storage (S3, GCS, Azure, R2), index files, and query retrieved chunks with metadata.