Skip to content
Tallyfy
Developers

Index multiple objects

Batch importing multiple objects

Section titled “Batch importing multiple objects”

This endpoint is how you add or update objects in Tallyfy Answers. You upload a JSON file holding an array of objects, and the service queues them for indexing.

Imports run in the background. You can see which collections have an import and stop one using the Tasks endpoints.

API endpoint

Section titled “API endpoint”
POST /collections/{collection_name}/batch

This endpoint needs the API key.

Request parameters

Section titled “Request parameters”
ParameterTypeRequiredDescription
collection_namepathYesName of the collection to import objects into

Request body format: a JSON file

Section titled “Request body format: a JSON file”

Send the request as multipart/form-data with one file field named data. The file holds a JSON array of objects. Give each object the seven fields search reads: uid, title, url, content, hierarchy, source and snippet.

Here’s an example JSON array format for two objects:

[
  {
    "uid": "article-123",
    "title": "Getting Started Guide",
    "content": "Complete guide to getting started...",
    "url": "https://example.com/guide",
    "hierarchy": {"lvl0": "Documentation", "lvl1": "Getting started"},
    "source": "Documentation",
    "snippet": "Quick start guide for new users"
  },
  {
    "uid": "article-456",
    "title": "Advanced Features",
    "content": "Advanced functionality overview...",
    "url": "https://example.com/advanced",
    "hierarchy": {"lvl0": "Documentation", "lvl1": "Advanced features"},
    "source": "Documentation",
    "snippet": "Deep dive into advanced capabilities"
  }
]

Content-Type header

Section titled “Content-Type header”

Use multipart/form-data. curl -F sets it for you.

Response

Section titled “Response”

A 200 OK means the import was queued, not finished:

{
  "valid": true,
  "message": "Processing data"
}

There’s no completion signal and no per-object error report. The service embeds and indexes the objects one at a time in a background thread, and an object that fails is only logged on the server. To see how far an import has got, compare counts from GET /collections/{collection_name}/objects/metadata.

An object whose uid already exists in the collection is updated in place.

A deploy or restart of the service ends any running import. If that happens, send the same file again. Objects already indexed are updated, not duplicated.

Error scenarios

Section titled “Error scenarios”
StatusDescription
400{"valid": false, "error": "Invalid JSON"}: the file isn’t valid JSON
400{"valid": false, "error": "JSON should be a list of objects"}: the file isn’t an array of objects
400Invalid collection name format
403The Authorization header is missing or doesn’t match the API key
404Collection not found
422The request has no file field named data
500{"valid": false, "error": "Internal server error"}

Example request using curl

Section titled “Example request using curl”
Terminal window
curl -X POST "https://answers.tallyfy.com/collections/docs/batch" \
  -H "Authorization: Bearer your_api_key" \
  -F "data=@objects.json;type=application/json"

Here objects.json holds an array like the one above. To add or update a single object, send an array with one object in it.

Best practices for batch imports

Section titled “Best practices for batch imports”
  • One import at a time per collection: Starting an import for a collection stops the one still running for it, and the objects it hadn’t reached are never indexed. Send one file per collection, and don’t send the next until the previous has finished.
  • ID handling: Give every object a uid. Objects without one can’t be updated, deleted on their own, or used for recommendations.
  • Parallel imports: You can run imports into different collections at the same time. Each one gets its own background thread.

When to use batch import

Section titled “When to use batch import”
  • Initial data population
  • Regular data synchronization from external systems
  • Bulk updates to multiple objects, by sending them again with their existing uid values
  • Periodic content refreshes
  • Adding or updating a single object
Section titled “Related articles”

Answers > Objects

Objects are the JSON records you store in a Tallyfy Answers collection. They’re indexed in…

Answers > Tasks

Tallyfy Answers runs batch imports in the background, so the import request doesn’t wait for…
Get in touch
About Tallyfy