Table of Contents

Collections and Documents

AIVAX provides a RAG (Retrieval-Augmented Generation) service for storing documents and retrieving them later through semantic search. A collection is an account-owned group of documents. Each document stores text, optional tags, an optional reference, optional metadata, and the vectors generated by the indexing job.

Collections can be searched directly through the RAG API or attached to an AI Gateway so retrieved documents can be injected into the model context.

Collections

Use collections to group documents that belong to the same knowledge base, product, tenant, language, or operational purpose.

A collection is the container you create before adding searchable knowledge. Think of it as the boundary for a knowledge base: a support collection can hold help-center answers, a legal collection can hold contract clauses, and a product collection can hold descriptions, policies, and troubleshooting notes. Later, you can search the collection directly with the Semantic Search API, expose it as an MCP tool, or attach it to an AI Gateway so retrieved documents are placed into the model context automatically.

Each collection has:

  • A unique collection ID.
  • A name.
  • Optional context and contextual tags.
  • A set of documents.
  • Usage statistics based on RAG transactions.

The Free plan currently allows up to 5 collections. Pro and Max do not define a collection-count limit in the current plan configuration.

Documents

A document is the unit that gets indexed and retrieved. It should be small enough to match a specific question and complete enough to be useful on its own.

This is the part that most affects RAG quality. A document should not be "everything you know" about a source; it should be one piece of knowledge that can stand alone when the model reads it later. If a user asks about cancellation fees, the retrieved document should already contain the relevant rule, product, condition, and exception. If the answer only makes sense when the model also sees the previous page, the document is probably too dependent on surrounding context.

A good document usually has:

  • A stable name.
  • Focused text.
  • Optional tags for filtering or maintenance.
  • Optional metadata for application-specific data.
  • An optional reference ID when the document is one chunk of a larger logical item.

For example, a car manual should not be indexed as one document. Index separate documents for topics such as starting the vehicle, checking tire pressure, pairing Bluetooth, and replacing a headlight. Each document should include enough context to be read independently. For broader chunking guidance, see Best Practices for RAG; for query behavior after indexing, see Semantic Search.

Document Fields

When you import documents in JSONL, each line represents one document that can be created or updated. The important field is docid: it is the stable name AIVAX uses to recognize the same document on future imports. If you send the same docid again with different text, the existing document is updated and reindexed. If you only need to preserve extra application data, use __meta instead of mixing that data into the searchable text.

The JSONL import endpoint accepts one JSON object per line:

Property Type Required Description
docid string Yes Stable document name. Existing documents are matched by this value.
text string Yes Text content to index semantically.
__ref string No Reference ID used to group related chunks. Maximum stored length is 64 characters.
__tags string[] No Tags for filtering, browsing, and maintenance.
__meta object No Metadata returned with document details and search results. Metadata is not the semantic text used for embeddings.

The document name must be non-empty and is limited by the API to 256 characters. The stored document content is required and cannot be empty.

Upserts and Reindexing

Documents are matched by name (docid in JSONL, Name in the single-document API).

When a document is created, it is queued for indexing. When existing document text changes, the document is queued again and its vectors are regenerated by the background indexer. When only __meta changes, metadata is updated without reindexing the document text.

Reference and tag values are stored with the document. In the single-document API, changed reference, tags, or metadata can update an existing document without reindexing when the text is unchanged. In the JSONL import endpoint, changed text queues reindexing, metadata-only changes update metadata without reindexing, and changed text can also update reference, tags, and metadata.

References

Use __ref when multiple documents represent parts of the same logical source, such as:

  • Sections of the same contract.
  • Clauses from the same policy.
  • Chunks from the same PDF.
  • Product fragments that should be shown together.

When search reference expansion is enabled, if one chunk matches, other documents in the same collection with the same reference can be included in the response.

Batch Import Limits

Batch import is sent as a JSONL file in the documents multipart field.

Use batch import when you already have many documents prepared outside AIVAX, such as chunks generated from PDFs, product catalogs, policies, or help-center articles. If you are creating or updating one document from an application flow, the single-document endpoint below is usually easier. If you are preparing a large knowledge base, import in batches, wait for indexing, and then test retrieval through Semantic Search before attaching the collection to a production gateway.

The current effective per-request JSONL line limits are:

Plan Maximum JSONL lines per request
Free 999
Pro 9,999
Max 999,999

Daily RAG insertion limits are separate from the per-request line limit:

Plan RAG insertions per day
Free 500
Pro 10,000
Max Not limited by the current plan configuration

If your import exceeds the request limit, split it into multiple files. If your account reaches the daily insertion limit, wait for the rate window to reset or upgrade the plan.

Warning

Indexing incurs cost based on document text tokens when documents are created or when their text changes.

Document Management

Create or update document

This endpoint is useful when your application manages documents one at a time. For example, an admin screen can save one FAQ entry, one policy clause, or one product note directly into a collection. AIVAX matches the document by name: changed text queues reindexing, while metadata-only changes update metadata without reindexing the content.

List documents

The browse endpoint helps you inspect what is already inside a collection. Use it when you need to verify an import, find a document by name, review queued versus indexed documents, or filter content before deciding whether to update, delete, or reimport part of the knowledge base.

Supported filters:

  • -t "tag": documents containing the tag.
  • -r "reference": documents with the exact reference ID.
  • -c "content": documents whose content contains the text snippet.
  • -n "name": documents whose name contains the text snippet.
  • -i "id": documents whose ID contains the supplied text.

Supported states:

  • queued: documents waiting for indexing.
  • indexed: documents already indexed.

Supported sort values:

  • created_at_asce
  • created_at_desc
  • updated_at_asce
  • updated_at_desc
  • indexed_at_asce
  • indexed_at_desc
Edit this page