search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

Custom API Sources, API Reference

Checkout the Custom API Sources Guide for a conceptual walkthrough.


Index, update, and destroy documents from a Custom API Source.

You can only create, update and destroy documents for a single Custom API Source at a time

See the API Overview to learn about authentication, schema design, field types, and more.

Index and Update Documents

Index new objects into a custom content source or update documents that already exist.

Schema fields are created automatically as text fields if they do not exist and cannot be deleted.

Maximum 100 documents per request.

The Five Keys of Schema Design

  1. Always index new fields as the same type as existing documents.
    • eg. An existing date field should not receive geolocation data.
  2. Arrays are supported, but nested objects are not supported. You must flatten them.
  3. Fields cannot be deleted once they have been created.
  4. The reserved fields are: external_id, source, content_source_id, updated_at, last_updated, highlight, any, all, none, or, and, not, engine_id.
  5. A field name can only contain lowercase letters, numbers, and underscores.
POST /api/v1/ent/sources/{content_source_key}/documents/bulk_create
access_token
required
Must be included in HTTP authorization headers.
content_source_key
required
Unique key for a Custom API source, provided upon creation of a Custom API Source.
id
optional
ID unique to a document used to identify, modify or delete the record at a later time. If you do not provide an id, a BSON id will be created for you. Learn more about ID.
Example - A POST request to index documents.
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_create \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  {
    "id" : 1234,
    "title" : "A List of Accounting Documents",
    "body" : "The difference between a budding entrepreneur who merely shows promise and one who is already enjoying some success often comes down to mentoring",
    "url" : "https://www.shopify.com/content/5-tips-on-finding-a-mentor",
    "created_at": "2019-06-01T12:00:00+00:00",
    "type": "list"
  }
]'
Example Response
[
  {
     "id":"1234",
     "errors":[]
  }
]

Example - A POST request to index documents.
No Java example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_create \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  {
    "id" : 1234,
    "title" : "A List of Accounting Documents",
    "body" : "The difference between a budding entrepreneur who merely shows promise and one who is already enjoying some success often comes down to mentoring",
    "url" : "https://www.shopify.com/content/5-tips-on-finding-a-mentor",
    "created_at": "2019-06-01T12:00:00+00:00",
    "type": "list"
  }
]'
Example Response
No Java example available, showing cURL
[
  {
     "id":"1234",
     "errors":[]
  }
]

Example - A POST request to index documents.
No Node example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_create \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  {
    "id" : 1234,
    "title" : "A List of Accounting Documents",
    "body" : "The difference between a budding entrepreneur who merely shows promise and one who is already enjoying some success often comes down to mentoring",
    "url" : "https://www.shopify.com/content/5-tips-on-finding-a-mentor",
    "created_at": "2019-06-01T12:00:00+00:00",
    "type": "list"
  }
]'
Example Response
No Node example available, showing cURL
[
  {
     "id":"1234",
     "errors":[]
  }
]

Example - A POST request to index documents.
No Ruby example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_create \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  {
    "id" : 1234,
    "title" : "A List of Accounting Documents",
    "body" : "The difference between a budding entrepreneur who merely shows promise and one who is already enjoying some success often comes down to mentoring",
    "url" : "https://www.shopify.com/content/5-tips-on-finding-a-mentor",
    "created_at": "2019-06-01T12:00:00+00:00",
    "type": "list"
  }
]'
Example Response
No Ruby example available, showing cURL
[
  {
     "id":"1234",
     "errors":[]
  }
]

Example - A POST request to index documents.
No Python example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_create \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  {
    "id" : 1234,
    "title" : "A List of Accounting Documents",
    "body" : "The difference between a budding entrepreneur who merely shows promise and one who is already enjoying some success often comes down to mentoring",
    "url" : "https://www.shopify.com/content/5-tips-on-finding-a-mentor",
    "created_at": "2019-06-01T12:00:00+00:00",
    "type": "list"
  }
]'
Example Response
No Python example available, showing cURL
[
  {
     "id":"1234",
     "errors":[]
  }
]

Example - A POST request to index documents.
No Javascript example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_create \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  {
    "id" : 1234,
    "title" : "A List of Accounting Documents",
    "body" : "The difference between a budding entrepreneur who merely shows promise and one who is already enjoying some success often comes down to mentoring",
    "url" : "https://www.shopify.com/content/5-tips-on-finding-a-mentor",
    "created_at": "2019-06-01T12:00:00+00:00",
    "type": "list"
  }
]'
Example Response
No Javascript example available, showing cURL
[
  {
     "id":"1234",
     "errors":[]
  }
]

Destroy Documents

Remove documents from a Custom API Source.

POST /api/v1/ent/sources/{content_source_key/documents/bulk_destroy
access_token
required
Must be included in HTTP authorization headers.
content_source_key
required
Unique key for a custom source, provided upon creation of a custom source.
id
required
An array of IDs associated to documents to destroy.
Example - A POST request to delete documents.
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_destroy \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  [DOCUMENT_ID_1], [DOCUMENT_ID_2]
]'
Example Response
[
 {
  "id":1234,
  "success":true
 },
 {
  "id":1235,
  "success":true
 }
]

Example - A POST request to delete documents.
No Java example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_destroy \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  [DOCUMENT_ID_1], [DOCUMENT_ID_2]
]'
Example Response
No Java example available, showing cURL
[
 {
  "id":1234,
  "success":true
 },
 {
  "id":1235,
  "success":true
 }
]

Example - A POST request to delete documents.
No Node example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_destroy \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  [DOCUMENT_ID_1], [DOCUMENT_ID_2]
]'
Example Response
No Node example available, showing cURL
[
 {
  "id":1234,
  "success":true
 },
 {
  "id":1235,
  "success":true
 }
]

Example - A POST request to delete documents.
No Ruby example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_destroy \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  [DOCUMENT_ID_1], [DOCUMENT_ID_2]
]'
Example Response
No Ruby example available, showing cURL
[
 {
  "id":1234,
  "success":true
 },
 {
  "id":1235,
  "success":true
 }
]

Example - A POST request to delete documents.
No Python example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_destroy \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  [DOCUMENT_ID_1], [DOCUMENT_ID_2]
]'
Example Response
No Python example available, showing cURL
[
 {
  "id":1234,
  "success":true
 },
 {
  "id":1235,
  "success":true
 }
]

Example - A POST request to delete documents.
No Javascript example available, showing cURL
curl -X POST http://localhost:3002/api/v1/ent/sources/[CONTENT_SOURCE_KEY]/documents/bulk_destroy \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  [DOCUMENT_ID_1], [DOCUMENT_ID_2]
]'
Example Response
No Javascript example available, showing cURL
[
 {
  "id":1234,
  "success":true
 },
 {
  "id":1235,
  "success":true
 }
]


Enjoying the beta? Something broken? Lost? Please send us your feedback or visit the Enterprise Search community.