Collections API (REST)

A collection defines the fields to index and the matching rules used to search them. Send the authentication headers with every request.

Endpoints

Method	Path	Result	Rights
GET	/collection	Array of collection names and indexId values	Read or Admin
POST	/collection	Create a collection; returns taskId	Write or Admin
GET	/collection/{id}	Name, structure, and matching configuration	Read or Admin
DELETE	/collection/{id}	Delete a collection; returns taskId	Admin
GET	/collection/configuration/{id}	Structure and matching configuration	Read or Admin
POST	/collection/clear/{id}	Clear documents; returns taskId	Admin
POST	/collection/state	Document counts for requested collections	Read or Admin

Collection identifiers are ULIDs. The /collection/configuration/{id} route instead takes the configuration record's UUID. Use GET /collection/{collectionId} when you have a collection ULID.

Create a collection

This example indexes the built-in content and title fields. Each structure field declares fieldType, store, datePrecision, and languagecode. Matching configuration contains a fields array; each entry names its output field and its input rules.

{
  "name": "Documents",
  "structure": {
    "fields": [
      {
        "name": "content",
        "fieldType": "MainContent",
        "store": "Yes",
        "datePrecision": "None",
        "languagecode": "ENG"
      },
      {
        "name": "title",
        "fieldType": "Text",
        "store": "Yes",
        "datePrecision": "None",
        "languagecode": "ENG"
      }
    ]
  },
  "matching": {
    "fields": [
      {
        "field": "content",
        "rules": [
          {
            "input": "content",
            "pattern": "Contains",
            "operand": "Or"
          }
        ]
      },
      {
        "field": "title",
        "rules": [
          {
            "input": "title",
            "pattern": "Contains",
            "operand": "Or"
          }
        ]
      }
    ]
  }
}

Download the request, then submit it:

curl --fail-with-body "$BLUECURVE_API_URL/collection" \
  -H "x-api-key: $BLUECURVE_API_KEY" \
  -H 'api-version: 1.0' \
  -H 'Content-Type: application/json' \
  --data-binary @create-collection.json

The response is HTTP 200 with { "taskId": "..." }. Poll the returned identifier through the Tasks API before ingesting into the collection. Use GET /collection to obtain its indexId.

An existing collection name returns 409. Invalid request fields return 400 with validation details. A missing collection returns 404 on get, clear, or delete. A processing failure can return 500.

Document counts

Send collection ULIDs to POST /collection/state:

{
  "indexIds": ["01J00000000000000000000000"]
}

The response is an array of { "indexId": "...", "docCount": 125032 } objects. These are collection counts, not per-task progress values.

Next: Jobs API