> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.airweave.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airweave.ai/_mcp/server.

# Create Collection

POST https://api.airweave.ai/collections
Content-Type: application/json

Create a new collection in your organization.

Collections are containers for organizing and searching across data from multiple
sources. After creation, add source connections to begin syncing data.

The collection will be assigned a unique `readable_id` based on the name you provide,
which is used in URLs and API calls. You can optionally configure:

- **Sync schedule**: How frequently to automatically sync data from all sources
- **Custom readable_id**: Provide your own identifier (must be unique and URL-safe)

Reference: https://docs.airweave.ai/api-reference/collections/create-collections-post

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /collections:
    post:
      operationId: create-collections-post
      summary: Create Collection
      description: >-
        Create a new collection in your organization.


        Collections are containers for organizing and searching across data from
        multiple

        sources. After creation, add source connections to begin syncing data.


        The collection will be assigned a unique `readable_id` based on the name
        you provide,

        which is used in URLs and API calls. You can optionally configure:


        - **Sync schedule**: How frequently to automatically sync data from all
        sources

        - **Custom readable_id**: Provide your own identifier (must be unique
        and URL-safe)
      tags:
        - collections
      parameters:
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Created collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionCreate'
servers:
  - url: https://api.airweave.ai
    description: Production
  - url: http://localhost:8001
    description: Local
components:
  schemas:
    DestinationConfig:
      type: object
      properties:
        skip_vespa:
          type: boolean
          default: false
          description: Skip writing to native Vespa
        target_destinations:
          type:
            - array
            - 'null'
          items:
            type: string
            format: uuid
          description: If set, ONLY write to these destination UUIDs
        exclude_destinations:
          type:
            - array
            - 'null'
          items:
            type: string
            format: uuid
          description: Skip these destination UUIDs
      description: Controls where entities are written.
      title: DestinationConfig
    HandlerConfig:
      type: object
      properties:
        enable_vector_handlers:
          type: boolean
          default: true
          description: Enable VectorDBHandler
        enable_raw_data_handler:
          type: boolean
          default: true
          description: Enable RawDataHandler (ARF)
        enable_postgres_handler:
          type: boolean
          default: true
          description: Enable EntityPostgresHandler
      description: Controls which handlers run during sync.
      title: HandlerConfig
    CursorConfig:
      type: object
      properties:
        skip_load:
          type: boolean
          default: false
          description: Don't load cursor (fetch all entities)
        skip_updates:
          type: boolean
          default: false
          description: Don't persist cursor progress
      description: Controls incremental sync cursor behavior.
      title: CursorConfig
    BehaviorConfig:
      type: object
      properties:
        skip_hash_comparison:
          type: boolean
          default: false
          description: Force INSERT for all entities
        replay_from_arf:
          type: boolean
          default: false
          description: Replay from ARF storage instead of calling source
        skip_guardrails:
          type: boolean
          default: false
          description: Skip usage guardrails (entity count checks)
      description: Miscellaneous execution behavior flags.
      title: BehaviorConfig
    SyncConfig:
      type: object
      properties:
        destinations:
          $ref: '#/components/schemas/DestinationConfig'
        handlers:
          $ref: '#/components/schemas/HandlerConfig'
        cursor:
          $ref: '#/components/schemas/CursorConfig'
        behavior:
          $ref: '#/components/schemas/BehaviorConfig'
      description: |-
        Sync configuration with automatic env var loading.

        Env vars use double underscore as delimiter:
            SYNC_CONFIG__HANDLERS__ENABLE_VECTOR_HANDLERS=false
      title: SyncConfig
    CollectionCreate:
      type: object
      properties:
        name:
          type: string
          description: >-
            Human-readable display name for the collection. This appears in the
            UI and should clearly describe the data contained within (e.g.,
            'Finance Data').
        readable_id:
          type:
            - string
            - 'null'
          description: >-
            URL-safe unique identifier used in API endpoints. Must contain only
            lowercase letters, numbers, and hyphens. If not provided, it will be
            automatically generated from the collection name with a random
            suffix for uniqueness (e.g., 'finance-data-ab123').
        sync_config:
          oneOf:
            - $ref: '#/components/schemas/SyncConfig'
            - type: 'null'
          description: >-
            Default sync configuration for all syncs in this collection. This
            provides collection-level defaults that can be overridden at sync or
            job level.
      required:
        - name
      description: >-
        Schema for creating a new collection.


        Collections serve as logical containers for organizing related data
        sources.

        Once created, you can add source connections to populate the collection
        with data

        from various sources like databases, APIs, and file systems.


        You can optionally set a default sync configuration that will apply to
        all syncs

        within this collection unless overridden at the sync or job level.
      title: CollectionCreate
    CollectionStatus:
      type: string
      enum:
        - ACTIVE
        - NEEDS SOURCE
        - ERROR
      description: Collection status enum.
      title: CollectionStatus
    SourceConnectionSummary:
      type: object
      properties:
        short_name:
          type: string
        name:
          type: string
      required:
        - short_name
        - name
      description: Lightweight summary of a source connection for collection list display.
      title: SourceConnectionSummary
    Collection:
      type: object
      properties:
        name:
          type: string
          description: Human-readable display name for the collection.
        readable_id:
          type: string
          description: >-
            URL-safe unique identifier used in API endpoints. This becomes
            non-optional once the collection is created.
        id:
          type: string
          format: uuid
          description: >-
            Unique system identifier for the collection. This UUID is generated
            automatically and used for internal references.
        sync_config:
          oneOf:
            - $ref: '#/components/schemas/SyncConfig'
            - type: 'null'
          description: >-
            Default sync configuration for all syncs in this collection.
            Overridable at sync and job level.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the collection was created (ISO 8601 format).
        modified_at:
          type: string
          format: date-time
          description: Timestamp when the collection was last modified (ISO 8601 format).
        organization_id:
          type: string
          format: uuid
          description: >-
            Identifier of the organization that owns this collection.
            Collections are isolated per organization.
        created_by_email:
          type:
            - string
            - 'null'
          format: email
          description: Email address of the user who created this collection.
        modified_by_email:
          type:
            - string
            - 'null'
          format: email
          description: Email address of the user who last modified this collection.
        status:
          $ref: '#/components/schemas/CollectionStatus'
          description: >-
            Current operational status of the collection:<br/>•
            **NEEDS_SOURCE**: Collection has no authenticated connections, or
            connections exist but haven't synced yet<br/>• **ACTIVE**: At least
            one connection has completed a sync or is currently syncing<br/>•
            **ERROR**: All connections have failed their last sync
        vector_size:
          type: integer
          description: >-
            Vector dimensions used by this collection (derived from deployment
            metadata).
        embedding_model_name:
          type: string
          description: >-
            Name of the embedding model used for this collection (derived from
            deployment metadata).
        source_connection_summaries:
          type: array
          items:
            $ref: '#/components/schemas/SourceConnectionSummary'
          description: >-
            Lightweight list of source connections attached to this collection.
            Contains only short_name and name, suitable for rendering icons in
            list views.
      required:
        - name
        - readable_id
        - id
        - created_at
        - modified_at
        - organization_id
        - vector_size
        - embedding_model_name
      description: >-
        API-facing collection schema with embedding metadata.


        Extends CollectionRecord with vector_size and embedding_model_name,
        which

        are resolved by the CollectionService from the deployment metadata and
        the

        dense embedder registry.


        Excludes vector_db_deployment_metadata_id (internal FK).
      title: Collection
    ValidationErrorDetail:
      type: object
      properties:
        loc:
          type: array
          items:
            type: string
          description: Location of the error (e.g., ['body', 'url'])
        msg:
          type: string
          description: Human-readable error message
        type:
          type: string
          description: Error type identifier
      required:
        - loc
        - msg
        - type
      description: Details about a validation error for a specific field.
      title: ValidationErrorDetail
    ValidationErrorResponse:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
          description: List of validation errors
      required:
        - detail
      description: |-
        Response returned when request validation fails (HTTP 422).

        This occurs when the request body contains invalid data, such as
        malformed URLs, invalid event types, or missing required fields.
      title: ValidationErrorResponse
    RateLimitErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message explaining the rate limit
      required:
        - detail
      description: >-
        Response returned when rate limit is exceeded (HTTP 429).


        The API enforces rate limits to ensure fair usage. When exceeded,

        wait for the duration specified in the Retry-After header before
        retrying.
      title: RateLimitErrorResponse
  securitySchemes:
    default:
      type: apiKey
      in: header
      name: x-api-key

```

## Examples



**Request**

```json
{
  "name": "Finance Data",
  "readable_id": "finance-data-reports"
}
```

**Response**

```json
{
  "name": "Finance Data",
  "readable_id": "finance-data-ab123",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z",
  "modified_at": "2024-01-15T14:22:15Z",
  "organization_id": "org12345-6789-abcd-ef01-234567890abc",
  "vector_size": 3072,
  "embedding_model_name": "text-embedding-3-large",
  "created_by_email": "admin@company.com",
  "modified_by_email": "finance@company.com",
  "status": "ACTIVE",
  "source_connection_summaries": [
    {
      "short_name": "slack",
      "name": "Slack"
    },
    {
      "short_name": "github",
      "name": "GitHub"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.airweave.ai/collections"

payload = {
    "name": "Finance Data",
    "readable_id": "finance-data-reports"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```typescript
import { AirweaveSDKClient } from "@airweave/sdk";

const client = new AirweaveSDKClient({ apiKey: "YOUR_API_KEY" });
await client.collections.create({
    name: "Finance Data",
    readable_id: "finance-data-reports"
});

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.airweave.ai/collections"

	payload := strings.NewReader("{\n  \"name\": \"Finance Data\",\n  \"readable_id\": \"finance-data-reports\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.airweave.ai/collections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Finance Data\",\n  \"readable_id\": \"finance-data-reports\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.airweave.ai/collections")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Finance Data\",\n  \"readable_id\": \"finance-data-reports\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.airweave.ai/collections', [
  'body' => '{
  "name": "Finance Data",
  "readable_id": "finance-data-reports"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.airweave.ai/collections");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Finance Data\",\n  \"readable_id\": \"finance-data-reports\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Finance Data",
  "readable_id": "finance-data-reports"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.airweave.ai/collections")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```