Control plane
Create vector index
Creates a vector index in a project.
POST /v1/projects/{project_id}/vector-indexes
- Choose an existing projectUse the project ID tied to your credential.
- Define the search shapeSet dense dimensions and metric, sparse vectors or text fields.
- Keep the index IDUse it for later record and search requests.
Before you start
Use your organization API key on the control-plane origin.
Use an existing dedicated project with vector-search entitlement. Creating an index does not provision new capacity.
Path parameters
| Field | Type | Required |
|---|---|---|
project_id | string | Required |
Request body
application/json
Limits and accepted values
- The JSON body is forwarded unchanged to the instance, which validates it;
- unknown keys are refused with 400.
- name: 1-45 characters of a-z, 0-9 and '-', starting and ending with a letter or digit, unique among the project's live indexes (409 otherwise).
- At least one of dimension (1-8192;
- above 8192 answers 402), sparse: true, or text_fields (at most 16) is required.
- metric (cosine|dot|l2|manhattan) is required with dimension and refused without it.
- visibility_fields: at most 16.
- deletion_protection: enabled|disabled (default disabled).
- identifier_profile: unicode|ascii (default unicode;
- frozen at creation;
- governs which characters namespace names may use).
- embedding (any non-null value answers 501) and metadata_publish (strict|immediate_when_not_embedding_input;
- answers 400) are recognised keys that are currently refused.
- Creating an index provisions no new capacity: it is added to the caller's existing dedicated instance, which holds at most 100 live indexes (402 beyond);
- the vector search add-on is required (402).
| Field | Type | Required |
|---|---|---|
name | string | Required |
dimension | integer | Optional |
metric | string | Optional |
sparse | boolean | Optional |
text_fields | object[] | Optional |
Fields in text_fields
| Field | Type | Required |
|---|---|---|
name | string | Required |
analyzer | string | Required |
| Field | Type | Required |
|---|---|---|
visibility_fields | string[] | Optional |
Fields in visibility_fields
| Field | Type | Required | Description |
|---|---|---|---|
visibility_fields | string | Optional | A metadata key: 1-512 bytes, not starting with $ or _oc, unique within the list. |
| Field | Type | Required | Description |
|---|---|---|---|
embedding | any JSON | Optional | — |
metadata_publish | string | Optional | — |
deletion_protection | string | Optional | — |
tags | object | Optional | Map of tag key (1-80 characters of A-Z, a-z, 0-9, _ and -) to tag value (at most 120 printable ASCII characters); at most 20 tags; an empty value is dropped. |
identifier_profile | string | Optional | — |
Read the result
Save index_id for record and search requests. dimension, metric and state describe the created index. This adds an index to an existing dedicated project; it does not provision a database.
Response statuses
HTTP status reference
| Status | What to do |
|---|---|
| 201 | Created |
| 400 | Correct the request before retrying. |
| 401 | Check the credential and Authorization header. |
| 402 | Check feature access or available credits. |
| 403 | Check tenant access, roles and permissions. |
| 404 | Check the resource ID and API route. |
| 409 | Resolve the conflict before retrying. |
| 415 | Send the required Content-Type. |
| 422 | Correct the values or unsupported combination. |
| 429 | Honor Retry-After when present; back off. |
| 500 | Check the outcome before retrying a write. |
| 501 | Check deployment support for this operation. |
| 502 | Check service availability and the write outcome. |
| 503 | Honor Retry-After when present; check write outcomes. |