Create collection

POST

/api/collections

curl --request POST \
  --url https://firma.company-gpt.com/companygpt/rag/api/api/collections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "displayName": "example", "description": "example", "visibility": "private", "searchLanguage": "english", "chunkingStrategy": "recursive", "chunkSize": 1, "chunkOverlap": 1, "type": "rag", "datasetMode": "imported", "tables": { "additionalProperty": { "columns": [ { "name": "example", "type": "text", "primary": true, "nullable": true } ], "relationships": [ {} ] } }, "structuredExtraction": { "enabled": true, "instructions": "example", "maxPages": 1 }, "embeddingModel": "example", "imageDescriptionsEnabled": false, "imageDescriptionMode": "all" }'

• CompanyGPT instance

Create a new collection. Either “name” or “displayName” must be provided. Creating a “dataset” collection with datasetMode=“live”, or a “rag” collection with structuredExtraction.enabled=true, also provisions backing Postgres tables.

Authorizations

• BearerAuth

Request Body^required

Media typeapplication/json

Either “name” or “displayName” must be provided (not enforceable as a plain JSON Schema required). When “datasetMode” is “live”, “tables” is required and describes the live-dataset schema; the same field also carries the extraction schema when structuredExtraction.enabled is true on a “rag” collection.

object

name

Technical name; auto-generated from displayName when omitted

string

displayName

string

description

string

visibility

string

default: private

Allowed values: private shared public

searchLanguage

PostgreSQL text search dictionary

string

default: english

chunkingStrategy

string

default: recursive

Allowed values: recursive markdown semantic

chunkSize

Only honoured when chunkingStrategy is “recursive”

integer

nullable

chunkOverlap

Only honoured when chunkingStrategy is “recursive”

integer

nullable

type

string

default: rag

Allowed values: rag dataset

datasetMode

Applies to type=“dataset” only

string

default: imported

Allowed values: imported live

tables

Required when datasetMode=“live”; also used as the extraction schema when structuredExtraction.enabled is true

object

key

additional properties

One table of a live-dataset / structured-extraction schema (livestore.TableDef)

object

columns

required

Array<object>

One column of a live-dataset / structured-extraction table (livestore.ColumnDef)

object

name

required

string

type

required

string

Allowed values: text integer numeric boolean timestamp

primary

Marks this column as the table’s natural key (dedup / upsert target). At most one per table.

boolean

nullable

Defaults to true when omitted; a primary column is always NOT NULL regardless of this value

boolean

nullable

relationships

Optional foreign-key style relationships between tables

Array<object>

object

structuredExtraction

Enables LLM field extraction on a “rag” collection (CreateCollectionRequest.structuredExtraction)

object

enabled

required

boolean

instructions

string

maxPages

Cost guardrail — caps how many pages of a document extraction scans. Omit or set <= 0 for no cap.

integer

nullable

embeddingModel

Catalog model id (see GET /api/embedding-models); falls back to the server default when omitted

string

imageDescriptionsEnabled

boolean

imageDescriptionMode

string

default: all

Allowed values: all empty_pages

Responses

201

Collection created

Media typeapplication/json

Collection record as returned by POST /api/collections, GET /api/collections/{id} and PUT /api/collections/{id} (database.Collection, encoded as-is — this is a different, lower-level shape than the enriched CollectionResponse used by the list endpoint).

object

id

required

string format: uuid

name

required

string

displayName

required

string

description

required

string

created_by

string format: uuid

nullable

owner_id

required

string format: uuid

visibility

required

string

Allowed values: private shared public

searchLanguage

required

PostgreSQL text search dictionary, e.g. “english”

string

type

required

string

Allowed values: rag dataset

chunkingStrategy

required

string

Allowed values: recursive markdown semantic

chunkSize

integer

nullable

chunkOverlap

integer

nullable

datasetMode

required

Empty for “rag” collections; “imported” or “live” for “dataset” collections

string

Allowed values: "" imported live

liveSchema

Live-dataset / structured-extraction schema (see LiveSchema)

object

lastIngestedAt

string format: date-time

nullable

structuredExtractionEnabled

required

boolean

extractionInstructions

Omitted from the JSON body when empty

string

extractionMaxPages

integer

nullable

imageDescriptionsEnabled

required

boolean

imageDescriptionMode

required

string

Allowed values: "" all empty_pages

embeddingModel

Omitted from the JSON body when empty

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "visibility": "private",
  "type": "rag",
  "chunkingStrategy": "recursive",
  "datasetMode": "",
  "imageDescriptionMode": ""
}

400

Invalid request (missing name/displayName, invalid schema, invalid enum value, etc.)

Media typeapplication/json

object

error

required

Error message

string

Example^generated

{
  "error": "example"
}

401

Unauthorized

409

A collection with this technical name already exists

500

Server error (including provisioning failures for live datasets / structured extraction)