---
title: "Create a corpus"
method: POST
path: "/v2/corpora"
tags: ["Corpora"]
---

# Create a corpus

`POST /v2/corpora`

Creates a corpus to store and manage your documents. A corpus is a container for documents and their associated metadata. You can set the corpus key, name, description, encoder, and filter attributes.

## Corpus object

The `key` property is required and uniquely identifies the corpus. The `name` property is optional and defaults to the value of `key`. The optional `description` property provides additional information about the corpus. You can choose a `key` that follows a naming convention of your choice. An identifiable key makes a corpus easier to manage and reference in your application.

Use the `queries_are_answers` and `documents_are_questions` boolean properties to treat queries or documents in the corpus as questions or answers. These settings affect the semantics of the encoder at query time and indexing time.

## Add metadata as filter attributes

Define metadata fields with the `filter_attributes` object when you create a corpus with this endpoint or the Vectara Console. The corpus then supports filtering on specific metadata attributes at the document level or the part level.

Filter attributes attach metadata to your data at the document (`doc`) or `part` level. You can use this metadata later in filter expressions to narrow the scope of your queries. A filter attribute must specify a unique `name` (up to 64 characters long) and a `level` of `doc` or `part`. At indexing time, the platform extracts metadata with this name and makes it available to filter expressions. [Learn more](https://docs.vectara.com/docs/build/prepare-data/metadata-filters)

### Doc and part filter levels

The `doc` attribute applies to the entire document. Use this for metadata that is consistent across the whole document, such as author, publication date, and document ID.

The `part` attribute applies to specific sections or chunks within a document. Use this for metadata that varies within different parts of the document, such as sections, page numbers, and sentiment scores.

If `indexed` is true, the platform builds an index on the extracted values. This index improves the performance of filter expressions that use the attribute.

Filter attributes must specify a `type`. The platform validates the type when documents are indexed. The four supported types are:
* `integer`: stores signed whole-number values up to eight bytes in length.
* `real`: stores floating point values in [IEEE 754 8-byte format].
* `text`: stores textual strings in [UTF-8 encoding].
* `boolean`: stores true/false values.

After you define filter attributes, you can use them within your queries. For example:
* Document-level attribute: `doc.publication_year > 2020`
* Part-level attribute: `part.sentiment_score > 0.7`

## Custom dimensions

Custom dimensions add user-defined values to your data, in addition to what the platform automatically extracts and stores from the text. For example, *upvotes* can be a custom dimension. For an example, see [Add custom dimensions to boost content](/docs/tutorials/add-custom-dimensions).

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- CreateCorpusRequest — Request object for creating a new corpus in the Vectara platform.
  - `key` string, required — A user-provided key for a corpus.
  - `name` string — The name for the corpus. This value defaults to the key.
  - `description` string — Description of the corpus.
  - `save_history` boolean — Indicates whether to save corpus queries to query history by default.
  - `queries_are_answers` boolean — Queries made to this corpus are considered answers, and not questions.
  - `documents_are_questions` boolean — Documents inside this corpus are considered questions, and not answers.
  - `encoder_id` string — *Deprecated*: Use `encoder_name` instead.
  - `encoder_name` string — The encoder used by the corpus, `boomerang-2023-q3`.
  - `filter_attributes` FilterAttribute[] — The filter attributes of the corpus. If unset, the corpus does not have filter attributes.
    - `name` string, required — The JSON path of the filter attribute in a document or document part metadata.
    - `level` 'document' | 'part', required — Indicates whether this is a document or document part metadata filter.
    - `description` string — A description of the filter. This property can be omitted.
    - `indexed` boolean — Whether to create an index for the filter. An index improves query latency for queries that use the filter.
    - `type` 'integer' | 'real_number' | 'text' | 'boolean' | 'list[integer]' | 'list[real_number]' | 'list[text]', required — The value type of the filter.
  - `custom_dimensions` CorpusCustomDimension[] — A custom dimension is an additional numerical field attached to a document part. You can then multiply this numerical field with a query time custom dimension of the same name. This allows boosting (or burying) document parts for arbitrary reasons. This feature is only enabled for Pro and Enterprise customers.
    - `name` string, required — The name of the custom dimension.
    - `description` string — Description of the custom dimension.
    - `indexing_default` number, double — The default value of a custom dimension on a document part. This value applies when the custom dimension value is not specified at indexing time. A value of 0 means that the custom dimension is not considered.
    - `querying_default` number, double — The default value of a custom dimension for a query. This value applies when the custom dimension value is not specified in the query. A value of 0 means that the custom dimension is not considered.

## Response `201`

The response includes a unique `id` that you use to reference the corpus. The `name` does not need to be unique within an account.

- Corpus — A corpus is a collection of documents and associated configuration for indexing, searching, and generating responses through RAG.
  - `id` string, required — Vectara ID of the corpus.
  - `key` string, required — A user-provided key for a corpus.
  - `name` string, required — Name for the corpus. This value defaults to the key.
  - `description` string — Corpus description.
  - `enabled` boolean — Specifies whether the corpus is enabled or not.
  - `chat_history_corpus` boolean — Indicates that this corpus does not store documents and stores chats instead.
  - `queries_are_answers` boolean — Queries made to this corpus are considered answers, and not questions. This swaps the semantics of the encoder used at query time.
  - `documents_are_questions` boolean — Documents inside this corpus are considered questions, and not answers. This swaps the semantics of the encoder used at indexing.
  - `encoder_id` string — The encoder used by the corpus. *Deprecated*: Use `encoder_name` instead
  - `encoder_name` string — The encoder used by the corpus, `boomerang-2023-q3`.
  - `save_history` boolean — Indicates whether to save corpus queries to query history by default.
  - `filter_attributes` FilterAttribute[] — The filter attributes of the corpus.
    - `name` string, required — The JSON path of the filter attribute in a document or document part metadata.
    - `level` 'document' | 'part', required — Indicates whether this is a document or document part metadata filter.
    - `description` string — A description of the filter. This property can be omitted.
    - `indexed` boolean — Whether to create an index for the filter. An index improves query latency for queries that use the filter.
    - `type` 'integer' | 'real_number' | 'text' | 'boolean' | 'list[integer]' | 'list[real_number]' | 'list[text]', required — The value type of the filter.
  - `custom_dimensions` CorpusCustomDimension[] — The custom dimensions of all document parts inside the corpus.
    - `name` string, required — The name of the custom dimension.
    - `description` string — Description of the custom dimension.
    - `indexing_default` number, double — The default value of a custom dimension on a document part. This value applies when the custom dimension value is not specified at indexing time. A value of 0 means that the custom dimension is not considered.
    - `querying_default` number, double — The default value of a custom dimension for a query. This value applies when the custom dimension value is not specified in the query. A value of 0 means that the custom dimension is not considered.
  - `limits` object
    - `used_docs` integer — The number of documents contained in the corpus.
    - `used_parts` integer — The number of document parts contained in the corpus.
    - `used_bytes` integer — NOTE: This field is currently not populated by the platform. The number of bytes contained in the corpus. This includes the document metadata, document part metadata, and document contents.
    - `used_characters` integer — The number of characters contained in the corpus. This includes the document metadata, document part metadata, and document contents.
    - `max_bytes` integer — NOTE: This field is currently not populated by the platform. The maximum number of bytes the corpus can be.
    - `max_metadata_bytes` integer — The maximum size that metadata can be on documents.
    - `index_rate` integer — NOTE: This field is currently not populated by the platform. The maximum per-second addition of new documents to corpus.
  - `created_at` string, date-time — Indicates when the corpus was created.

## Other responses

- `400` — Invalid request body in the create corpus request.
- `403` — Permissions do not allow creating a corpus.
- `409` — The corpus already exists

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/e85040b266cc/schema)