--- title: "POST /v2/namespaces/{namespace}" method: POST path: "/v2/namespaces/{namespace}" --- # POST /v2/namespaces/{namespace} `POST /v2/namespaces/{namespace}` Create, update, or delete documents. ## Path parameters - `namespace` string, required ## Request body - Write — Create, update, or delete documents. - `upsert_columns` Columns — A list of documents in columnar format. Each key is a column name, mapped to an array of values for that column. - `id` Id[], required — The IDs of the documents. - union — An identifier for a document. - string, uuid — A UUID. - string — A string ID. - integer — An integer ID. - `vector` union - Vector[] — The vector embeddings of the documents. - union — A vector embedding associated with a document. - number[] — A dense vector encoded as an array of floats. - string — A dense vector encoded as a base64 string. - union — A vector embedding associated with a document. - number[] — A dense vector encoded as an array of floats. - string — A dense vector encoded as a base64 string. - `upsert_rows` Row[] - `id` union, required — An identifier for a document. - string, uuid — A UUID. - string — A string ID. - integer — An integer ID. - `vector` union — A vector embedding associated with a document. - number[] — A dense vector encoded as an array of floats. - string — A dense vector encoded as a base64 string. - `patch_columns` Columns — A list of documents in columnar format. Each key is a column name, mapped to an array of values for that column. - `id` Id[], required — The IDs of the documents. - union — An identifier for a document. - string, uuid — A UUID. - string — A string ID. - integer — An integer ID. - `vector` union - Vector[] — The vector embeddings of the documents. - union — A vector embedding associated with a document. - number[] — A dense vector encoded as an array of floats. - string — A dense vector encoded as a base64 string. - union — A vector embedding associated with a document. - number[] — A dense vector encoded as an array of floats. - string — A dense vector encoded as a base64 string. - `patch_rows` Row[] - `id` union, required — An identifier for a document. - string, uuid — A UUID. - string — A string ID. - integer — An integer ID. - `vector` union — A vector embedding associated with a document. - number[] — A dense vector encoded as an array of floats. - string — A dense vector encoded as a base64 string. - `deletes` Id[] - union — An identifier for a document. - string, uuid — A UUID. - string — A string ID. - integer — An integer ID. - `upsert_condition` unknown - `patch_condition` unknown - `delete_condition` unknown - `distance_metric` union — A function used to calculate vector similarity. - 'cosine_distance' — Defined as `1 - cosine_similarity` and ranges from 0 to 2. Lower is better. - 'euclidean_squared' — Defined as `sum((x - y)^2)`. Lower is better. - `schema` object — The schema of the attributes attached to the documents. - `branch_from_namespace` union - string — The namespace to create an instant, copy-on-write clone of. - BranchFromNamespaceConfig - `source_namespace` string, required — The namespace to create an instant, copy-on-write clone of. - `copy_from_namespace` union - string — The namespace to copy documents from. - CopyFromNamespaceConfig - `source_namespace` string, required — The namespace to copy documents from. - `source_api_key` string — (Optional) An API key for the organization containing the source namespace - `source_region` string — (Optional) The region of the source namespace. - `delete_by_filter` unknown - `delete_by_filter_allow_partial` boolean — Allow partial completion when filter matches too many documents. - `patch_by_filter` PatchByFilter — The patch and filter specifying which documents to patch. - `patch` object, required - `filters` unknown, required - `patch_by_filter_allow_partial` boolean — Allow partial completion when filter matches too many documents. - `return_affected_ids` boolean — If true, return the IDs of affected rows (deleted, patched, upserted) in the response. For filtered and conditional writes, only IDs for writes that succeeded will be included. - `encryption` union — The encryption configuration for a namespace. - object — Encrypt the namespace with a customer-managed encryption key (CMEK). - `mode` 'customer-managed', required - `key_name` string, required — The identifier of the CMEK key to use for encryption. For GCP, the fully-qualified resource name of the key. For AWS, the ARN of the key. - object — Use the default server-side encryption (SSE). - `mode` 'default', required - `sharding` ShardingConfig — Configuration for namespace sharding, which partitions a namespace's documents across multiple internal shards to scale indexing and query throughput beyond a single machine. Sharding can only be configured on a namespace's inaugural write, and cannot be added to or changed on an existing namespace. - `num_shards` integer, required — The number of shards to partition the namespace into. - `disable_backpressure` boolean — Disables write throttling (HTTP 429 responses) during high-volume ingestion. ## Response `200` The status of the request. - WriteResult — The response to a successful write request. - `status` 'OK', required — The status of the request. - `message` string, required — A message describing the result of the write request. - `rows_affected` integer, required — The number of rows affected by the write request. - `rows_upserted` integer — The number of rows upserted by the write request. - `rows_patched` integer — The number of rows patched by the write request. - `rows_deleted` integer — The number of rows deleted by the write request. - `rows_remaining` boolean — Whether more documents match the filter for partial operations. - `upserted_ids` Id[] — The IDs of documents that were upserted. Only included when `return_affected_ids` is true and at least one document was upserted. - union — An identifier for a document. - string, uuid — A UUID. - string — A string ID. - integer — An integer ID. - `patched_ids` Id[] — The IDs of documents that were patched. Only included when `return_affected_ids` is true and at least one document was patched. - union — An identifier for a document. - string, uuid — A UUID. - string — A string ID. - integer — An integer ID. - `deleted_ids` Id[] — The IDs of documents that were deleted. Only included when `return_affected_ids` is true and at least one document was deleted. - union — An identifier for a document. - string, uuid — A UUID. - string — A string ID. - integer — An integer ID. - `billing` WriteBilling, required — The billing information for a write request. - `billable_logical_bytes_written` integer, required — The number of billable logical bytes written to the namespace. - `query` QueryBilling — The billing information for a query. - `billable_logical_bytes_queried` integer, required — The number of billable logical bytes queried from the namespace. - `billable_logical_bytes_returned` integer, required — The number of billable logical bytes returned from the query. - `performance` WritePerformance — The performance information for a write request. - `server_total_ms` integer, required — Request time measured on the server, in milliseconds. ## Other responses - `default` — An error response. --- [API](https://skmtc.net/turbopuffer/apis/turbopuffer-api.md) · [All operations](https://skmtc.net/turbopuffer/apis/turbopuffer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/turbopuffer/turbopuffer-api/versions/245e887f04ab/schema)