Skip to main content
POST
/
v1
/
collections
Create Collection
curl --request POST \
  --url https://api.example.com/v1/collections \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "readable_id": "<string>",
  "sync_config": {
    "handlers": {
      "enable_vector_handlers": true,
      "enable_postgres_handler": true
    }
  }
}
'
{
  "id": "<string>",
  "name": "<string>",
  "readable_id": "<string>",
  "status": "<string>",
  "vector_size": 123,
  "embedding_model_name": "<string>",
  "created_at": "<string>",
  "organization_id": "<string>"
}

​
Overview

Create a new collection to organize and search 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.

​
Request Body

​
name
string
required
Human-readable display name for the collection (4-64 characters)Example: “Finance Data”, “Customer Support”
​
readable_id
string
Custom URL-safe identifier. If not provided, auto-generated from name.Must contain only lowercase letters, numbers, and hyphens.Example: “finance-data-reports”
​
sync_config
object
Default sync configuration for all syncs in this collection

​
Response

Returns the created collection object.
​
id
string
required
Unique UUID identifier for the collection
​
name
string
required
Human-readable display name
​
readable_id
string
required
URL-safe unique identifier
​
status
string
required
Initial status will be NEEDS_SOURCE
​
vector_size
integer
required
Vector dimensions used by this collection
​
embedding_model_name
string
required
Name of the embedding model used
​
created_at
string
required
ISO 8601 timestamp when created
​
organization_id
string
required
UUID of your organization

​
Example Request

curl -X POST https://api.airweave.ai/v1/collections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance Data",
    "readable_id": "finance-data-reports"
  }'

​
Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Finance Data",
  "readable_id": "finance-data-reports",
  "vector_size": 3072,
  "embedding_model_name": "text-embedding-3-large",
  "sync_config": null,
  "created_at": "2024-01-15T09:30:00Z",
  "modified_at": "2024-01-15T09:30:00Z",
  "organization_id": "org12345-6789-abcd-ef01-234567890abc",
  "created_by_email": "admin@company.com",
  "modified_by_email": "admin@company.com",
  "status": "NEEDS_SOURCE"
}

​
Error Responses

​
400 Bad Request
Collection with the specified readable_id already exists
​
422 Validation Error
Invalid request body (e.g., name too short, invalid readable_id format)