{ "openapi": "3.1.0", "info": { "title": "OriginChainDB Control Plane API", "version": "1.0.0", "description": "Control-plane operations you can call from code: managed embeddings and vector projects. Database management (creating databases, members, billing) is done in the console. For server-side use: these routes are not enabled for cross-origin browser calls." }, "servers": [ { "url": "https://api.originchain.ai" } ], "paths": { "/v1/embed-credits": { "get": { "operationId": "get_embedding_credits", "summary": "Returns your organization's embedding credit balance, its one-time trial grant and the number of tokens embedded this calendar month.", "tags": [ "embeddings" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance_micro_usd": { "type": "integer" }, "trial_granted_micro_usd": { "type": "integer" }, "month_tokens": { "type": "integer" } }, "required": [ "balance_micro_usd", "month_tokens", "trial_granted_micro_usd" ], "description": "Amounts are integer micro-USD (1,000,000 = 1 USD). balance_micro_usd can be slightly negative after concurrent embedding requests. trial_granted_micro_usd is always present and is null when no trial grant has been recorded; the grant is applied on the organization's first embeddings request, not by this call. month_tokens counts tokens billed since the start of the current UTC calendar month." } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "security": [ { "orgApiKey": [] } ] } }, "/v1/embed-credits/history": { "get": { "operationId": "list_embedding_credit_history", "summary": "Lists your organization's 200 most recent embedding credit ledger entries, newest first.", "tags": [ "embeddings" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "delta_micro_usd": { "type": "integer" }, "model_id": { "type": "string" }, "tokens": { "type": "integer" }, "created_at": { "type": "string" } }, "required": [ "created_at", "delta_micro_usd", "id", "kind", "model_id", "tokens" ], "description": "kind is one of trial_grant, purchase, debit, adjustment. delta_micro_usd is signed integer micro-USD (negative for debits). model_id and tokens are always present and are null for entries that are not tied to a model (grants, purchases, adjustments). created_at is an RFC 3339 UTC timestamp." } } }, "required": [ "entries" ], "description": "Returns at most 200 entries ordered by id descending; there is no pagination." } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "security": [ { "orgApiKey": [] } ] } }, "/v1/embeddings": { "post": { "operationId": "create_embeddings", "summary": "Creates embedding vectors for the given input with the selected embedding model and debits the cost from your organization's embedding credits.", "tags": [ "embeddings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "input": {} }, "required": [ "input", "model" ], "description": "model must be a catalog id that is currently available and priced (otherwise 400 for an unknown or unavailable model, 403 for an unpriced one); a missing or non-string model is rejected with 422. input is declared optional for parsing but the route rejects an absent, null or empty-array input with 400: send a single item (a string, or an object with exactly one of text or image) or an array of items, up to the deployment's batch limit (400 above it). Any additional fields (for example input_type, query or document) are forwarded unchanged to the embedding service." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "model": { "type": "string" }, "dim": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "index": { "type": "integer" }, "embedding": { "type": "array", "items": { "type": "number" } } } } }, "usage": { "type": "object", "properties": { "total_tokens": { "type": "integer" } } } }, "description": "The body is relayed verbatim from the embedding service and is not validated by this route, so every field is marked optional; the current embedding service returns an OpenAI-compatible list (object \"list\", model, dim, data[] of {object \"embedding\", index, embedding}, usage.total_tokens). Billing uses usage.total_tokens. When the debit succeeds the response carries an x-oc-credits-balance header with the remaining balance in integer micro-USD." } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "orgApiKey": [] } ] } }, "/v1/embeddings/catalog": { "get": { "operationId": "list_embedding_models", "summary": "Lists the embedding models offered to your organization, with each model's dimensions, supported input types, availability and price.", "tags": [ "embeddings" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "embedder_reachable": { "type": "boolean" }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "dim": { "type": "integer" }, "text": { "type": "boolean" }, "image": { "type": "boolean" }, "available": { "type": "boolean" }, "price_micro_usd_per_1m": { "type": "integer" } }, "required": [ "available", "dim", "id", "image", "price_micro_usd_per_1m", "provider", "text" ], "description": "available is true only when the model can be served right now and is priced. price_micro_usd_per_1m is integer micro-USD per one million tokens and is null for a model that is not offered for purchase. When the model is not currently served, dim is 0, text defaults to true and image to false." } } }, "required": [ "embedder_reachable", "models" ], "description": "models is sorted by id. embedder_reachable is false when live model data is unavailable; priced models are still listed, with available false." } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "security": [ { "orgApiKey": [] } ] } }, "/v1/projects": { "get": { "operationId": "list_projects", "summary": "Lists the project that the presented API key belongs to.", "tags": [ "vector-projects" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "host_token_state": { "type": "string" } }, "required": [ "host_token_state", "id", "name" ], "description": "id is a UUID (the project_id used by the index routes); name is the instance's name when the project was created; host_token_state is one of pending|bound|deferred|unsupported|conflict and reports whether the project's per-index data-plane host names have been published to the instance." } } }, "required": [ "data" ], "description": "Always exactly one element: the project of the dedicated instance the key was issued for. The project is created on first sight if it does not exist yet (no cost). Read-only keys are allowed." } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" } }, "security": [ { "engineUserToken": [] }, { "engineUserApiKey": [] } ] } }, "/v1/projects/{project_id}/vector-indexes": { "get": { "operationId": "list_vector_indexes", "summary": "Lists the vector indexes in a project, in ascending name order, one page at a time.", "tags": [ "vector-projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "indexes": { "type": "array", "items": { "type": "object", "properties": { "index_id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "dimension": { "type": "integer" }, "metric": { "type": "string" }, "score_direction": { "type": "string" }, "sparse": { "type": "boolean" }, "text_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "analyzer": { "type": "string" } }, "required": [ "analyzer", "name" ] } }, "visibility_fields": { "type": "array", "items": { "type": "string" } }, "embedding": { "type": "object", "properties": { "model_config_id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "revision": { "type": "string" }, "dimension": { "type": "integer" }, "dtype": { "type": "string" }, "metric": { "type": "string" }, "preprocessing_version": { "type": "string" }, "document_task": { "type": "string" }, "query_task": { "type": "string" } }, "required": [ "dimension", "document_task", "dtype", "metric", "model", "model_config_id", "preprocessing_version", "provider", "query_task", "revision" ], "description": "Always present and null on every index today (generated-embedding indexes cannot be created yet); when an object, revision may be null, dtype is f32 and metric is cosine|dot|l2|manhattan." }, "deletion_protection": { "type": "string" }, "tags": { "type": "object", "description": "Map of tag key to tag value (both strings); empty object when the index has no tags." }, "identifier_profile": { "type": "string" }, "compat_family": { "type": "string" }, "created_at": { "type": "string" }, "project_id": { "type": "string" } }, "required": [ "compat_family", "created_at", "deletion_protection", "embedding", "identifier_profile", "index_id", "name", "project_id", "score_direction", "sparse", "state", "tags", "text_fields", "visibility_fields" ], "description": "The index object. state: active (deleting indexes are not listed); index_id: 26-character ULID; dimension and metric (cosine|dot|l2|manhattan) are omitted when the index has no dense vectors; score_direction: always higher_is_better; deletion_protection: enabled|disabled; identifier_profile: unicode|ascii; compat_family: documents|records|vectors|none; created_at: RFC 3339 UTC with milliseconds; project_id (UUID) is added by the control plane." } }, "next_cursor": { "type": "string" } }, "required": [ "indexes" ], "description": "The instance's listing passed through with project_id added to each index. Only indexes the key holds a grant on are listed. next_cursor is present only when more may follow; send it back as cursor with the same prefix and limit. limit is 1-100 (default 100; a non-integer is refused by the control plane, an out-of-range value by the instance, both 400); prefix is 1-45 characters of a-z, 0-9 and '-'." } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "engineUserToken": [] }, { "engineUserApiKey": [] } ] }, "post": { "operationId": "create_vector_index", "summary": "Creates a vector index in a project.", "tags": [ "vector-projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "dimension": { "type": "integer" }, "metric": { "type": "string" }, "sparse": { "type": "boolean" }, "text_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "analyzer": { "type": "string" } }, "required": [ "analyzer", "name" ], "description": "name matches ^[a-z][a-z0-9_]{0,63}$ and is unique within the index; analyzer is 1-64 printable ASCII characters." } }, "visibility_fields": { "type": "array", "items": { "type": "string", "description": "A metadata key: 1-512 bytes, not starting with $ or _oc, unique within the list." } }, "embedding": {}, "metadata_publish": { "type": "string" }, "deletion_protection": { "type": "string" }, "tags": { "type": "object", "description": "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": { "type": "string" } }, "required": [ "name" ], "description": "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)." } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "index_id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "dimension": { "type": "integer" }, "metric": { "type": "string" }, "score_direction": { "type": "string" }, "sparse": { "type": "boolean" }, "text_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "analyzer": { "type": "string" } }, "required": [ "analyzer", "name" ] } }, "visibility_fields": { "type": "array", "items": { "type": "string" } }, "embedding": { "type": "object", "properties": { "model_config_id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "revision": { "type": "string" }, "dimension": { "type": "integer" }, "dtype": { "type": "string" }, "metric": { "type": "string" }, "preprocessing_version": { "type": "string" }, "document_task": { "type": "string" }, "query_task": { "type": "string" } }, "required": [ "dimension", "document_task", "dtype", "metric", "model", "model_config_id", "preprocessing_version", "provider", "query_task", "revision" ], "description": "Always present and null on every index today (generated-embedding indexes cannot be created yet); when an object, revision may be null, dtype is f32 and metric is cosine|dot|l2|manhattan." }, "deletion_protection": { "type": "string" }, "tags": { "type": "object", "description": "Map of tag key to tag value (both strings); empty object when the index has no tags." }, "identifier_profile": { "type": "string" }, "compat_family": { "type": "string" }, "created_at": { "type": "string" }, "project_id": { "type": "string" } }, "required": [ "compat_family", "created_at", "deletion_protection", "embedding", "identifier_profile", "index_id", "name", "project_id", "score_direction", "sparse", "state", "tags", "text_fields", "visibility_fields" ], "description": "201 with the new index object (state active), passed through from the instance with project_id (UUID) added by the control plane. index_id: 26-character ULID; dimension and metric are omitted when the index has no dense vectors; score_direction: always higher_is_better; deletion_protection: enabled|disabled; identifier_profile: unicode|ascii; compat_family: documents|records|vectors|none; created_at: RFC 3339 UTC with milliseconds. The index is born holding its default namespace." } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "engineUserToken": [] }, { "engineUserApiKey": [] } ] } }, "/v1/projects/{project_id}/vector-indexes/{index_name}": { "delete": { "operationId": "delete_vector_index", "summary": "Deletes a vector index and, in the background, all of its records.", "tags": [ "vector-projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "index_id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "dimension": { "type": "integer" }, "metric": { "type": "string" }, "score_direction": { "type": "string" }, "sparse": { "type": "boolean" }, "text_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "analyzer": { "type": "string" } }, "required": [ "analyzer", "name" ] } }, "visibility_fields": { "type": "array", "items": { "type": "string" } }, "embedding": { "type": "object", "properties": { "model_config_id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "revision": { "type": "string" }, "dimension": { "type": "integer" }, "dtype": { "type": "string" }, "metric": { "type": "string" }, "preprocessing_version": { "type": "string" }, "document_task": { "type": "string" }, "query_task": { "type": "string" } }, "required": [ "dimension", "document_task", "dtype", "metric", "model", "model_config_id", "preprocessing_version", "provider", "query_task", "revision" ], "description": "Always present and null on every index today (generated-embedding indexes cannot be created yet); when an object, revision may be null, dtype is f32 and metric is cosine|dot|l2|manhattan." }, "deletion_protection": { "type": "string" }, "tags": { "type": "object", "description": "Map of tag key to tag value (both strings); empty object when the index has no tags." }, "identifier_profile": { "type": "string" }, "compat_family": { "type": "string" }, "created_at": { "type": "string" }, "project_id": { "type": "string" } }, "required": [ "compat_family", "created_at", "deletion_protection", "embedding", "identifier_profile", "index_id", "name", "project_id", "score_direction", "sparse", "state", "tags", "text_fields", "visibility_fields" ], "description": "202 with the index object in state deleting, passed through from the instance with project_id (UUID) added by the control plane. Irreversible: the name is free for reuse immediately and the index's records are erased in the background. :index_name is an index name or a 26-character uppercase ULID index_id. Needs a read-write key and the manage action on the index. 409 deletion_protection_enabled when deletion protection is on (disable it with configure_vector_index first); 409 record_write_conflict (retryable) on a concurrent change." } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "engineUserToken": [] }, { "engineUserApiKey": [] } ] }, "get": { "operationId": "describe_vector_index", "summary": "Returns the configuration and state of one vector index, addressed by name or by index ID.", "tags": [ "vector-projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "index_id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "dimension": { "type": "integer" }, "metric": { "type": "string" }, "score_direction": { "type": "string" }, "sparse": { "type": "boolean" }, "text_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "analyzer": { "type": "string" } }, "required": [ "analyzer", "name" ] } }, "visibility_fields": { "type": "array", "items": { "type": "string" } }, "embedding": { "type": "object", "properties": { "model_config_id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "revision": { "type": "string" }, "dimension": { "type": "integer" }, "dtype": { "type": "string" }, "metric": { "type": "string" }, "preprocessing_version": { "type": "string" }, "document_task": { "type": "string" }, "query_task": { "type": "string" } }, "required": [ "dimension", "document_task", "dtype", "metric", "model", "model_config_id", "preprocessing_version", "provider", "query_task", "revision" ], "description": "Always present and null on every index today (generated-embedding indexes cannot be created yet); when an object, revision may be null, dtype is f32 and metric is cosine|dot|l2|manhattan." }, "deletion_protection": { "type": "string" }, "tags": { "type": "object", "description": "Map of tag key to tag value (both strings); empty object when the index has no tags." }, "identifier_profile": { "type": "string" }, "compat_family": { "type": "string" }, "created_at": { "type": "string" }, "project_id": { "type": "string" } }, "required": [ "compat_family", "created_at", "deletion_protection", "embedding", "identifier_profile", "index_id", "name", "project_id", "score_direction", "sparse", "state", "tags", "text_fields", "visibility_fields" ], "description": "The index object passed through from the instance with project_id (UUID) added by the control plane. :index_name is an index name (1-45 characters of a-z, 0-9 and '-') or a 26-character uppercase ULID index_id; anything else answers 400 before the instance is called. A missing index, a deleting index and an index the key holds no grant on all answer 404 index_not_found. state: active; dimension and metric (cosine|dot|l2|manhattan) omitted when the index has no dense vectors; score_direction: always higher_is_better; deletion_protection: enabled|disabled; identifier_profile: unicode|ascii; compat_family: documents|records|vectors|none; created_at: RFC 3339 UTC with milliseconds." } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "engineUserToken": [] }, { "engineUserApiKey": [] } ] }, "patch": { "operationId": "configure_vector_index", "summary": "Changes the deletion protection or the tags of a vector index.", "tags": [ "vector-projects" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deletion_protection": { "type": "string" }, "tags": { "type": "object", "description": "Map of tag key (1-80 characters of A-Z, a-z, 0-9, _ and -) to tag value (at most 120 printable ASCII characters). Merged into the existing tags; an empty-string value removes that tag; more than 20 tags after the merge answers 400 and changes nothing." } }, "description": "The JSON body is forwarded unchanged to the instance. At least one of deletion_protection (enabled|disabled) or tags is required (400 otherwise). Naming any other index field (name, dimension, metric, sparse, text_fields, visibility_fields, embedding, metadata_publish, identifier_profile, index_id, state, score_direction, compat_family, created_at) answers 400 immutable_field; any unknown key answers 400. A body that is not valid JSON answers 400 before the key is checked." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "index_id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "dimension": { "type": "integer" }, "metric": { "type": "string" }, "score_direction": { "type": "string" }, "sparse": { "type": "boolean" }, "text_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "analyzer": { "type": "string" } }, "required": [ "analyzer", "name" ] } }, "visibility_fields": { "type": "array", "items": { "type": "string" } }, "embedding": { "type": "object", "properties": { "model_config_id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "revision": { "type": "string" }, "dimension": { "type": "integer" }, "dtype": { "type": "string" }, "metric": { "type": "string" }, "preprocessing_version": { "type": "string" }, "document_task": { "type": "string" }, "query_task": { "type": "string" } }, "required": [ "dimension", "document_task", "dtype", "metric", "model", "model_config_id", "preprocessing_version", "provider", "query_task", "revision" ], "description": "Always present and null on every index today (generated-embedding indexes cannot be created yet); when an object, revision may be null, dtype is f32 and metric is cosine|dot|l2|manhattan." }, "deletion_protection": { "type": "string" }, "tags": { "type": "object", "description": "Map of tag key to tag value (both strings); empty object when the index has no tags." }, "identifier_profile": { "type": "string" }, "compat_family": { "type": "string" }, "created_at": { "type": "string" }, "project_id": { "type": "string" } }, "required": [ "compat_family", "created_at", "deletion_protection", "embedding", "identifier_profile", "index_id", "name", "project_id", "score_direction", "sparse", "state", "tags", "text_fields", "visibility_fields" ], "description": "200 with the updated index object, passed through from the instance with project_id (UUID) added by the control plane. :index_name is an index name or a 26-character uppercase ULID index_id. Needs a read-write key and the manage action on the index. 409 record_write_conflict (retryable) when the index changed concurrently. Field values as in describe_vector_index." } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [ { "engineUserToken": [] }, { "engineUserApiKey": [] } ] } } }, "components": { "securitySchemes": { "orgApiKey": { "type": "http", "scheme": "bearer", "description": "An org API key (starts with ock_). Create one in the console." }, "engineUserToken": { "type": "http", "scheme": "bearer", "description": "Your own database user key (starts with oc_u_), as a bearer token." }, "engineUserApiKey": { "type": "apiKey", "in": "header", "name": "Api-Key", "description": "The same database user key (oc_u_...) in an Api-Key header." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "description": "The control plane's error object, or a plain string on some errors passed through from a database (e.g. 429).", "oneOf": [ { "type": "object", "required": [ "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code (absent when an embedding-service error is passed through)." }, "message": { "type": "string", "description": "Human-readable message." }, "type": { "type": "string", "description": "Error type, present on errors passed through from the embedding service." }, "instance_id": { "type": "string", "description": "The database the error concerns, on database-scoped errors." } }, "additionalProperties": true }, { "type": "string" } ] } }, "description": "Every error, including a malformed body or an unknown route, uses this shape. Retryable errors carry a Retry-After header." } }, "responses": { "Error": { "description": "Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }