{ "openapi": "3.1.0", "info": { "title": "Hanzo Cloud API", "description": "Package provisioning is one-click data add-ons: a SQL, key-value, document, vector, search or object store, wired straight into your app.", "version": "v1" }, "servers": [ { "url": "https://api.hanzo.ai" } ], "tags": [ { "name": "datastore" }, { "name": "docdb" }, { "name": "kv" }, { "name": "s3" }, { "name": "search" }, { "name": "sql" }, { "name": "vector" } ], "paths": { "/v1/datastore": { "get": { "operationId": "get_v1_datastore", "summary": "Lists the caller org's Hanzo Datastore warehouses.", "description": "Lists the caller org's Hanzo Datastore warehouses. Each one is\na DEDICATED analytical instance the org alone runs, so the host is that\ninstance's own in-cluster Service and the port is its HTTP port, 8123.", "tags": [ "datastore" ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/provisionedSummary" }, "type": "array" } } }, "description": "ok" } } }, "post": { "operationId": "post_v1_datastore", "summary": "Provision a Hanzo Datastore instance for your org", "description": "Launches your org's OWN Hanzo Datastore instance and answers with its `datastore://` connection string. The instance is yours alone: a deployment in your own tenant namespace, so its admin credential is naturally scoped to you and no other tenant shares the process. Off-cluster, where there is no orchestrator to launch one, this fails closed with 503 rather than handing back a shared one.\n\n`name` is the org-unique slug every physical name derives from, and must match ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$. `instance` optionally BINDS the add-on to one of your app instances: the DSN is injected into that instance's addons secret as \u003cKIND\u003e_URL, switching the app off its built-in store and onto this one. Omit it and the connection string is yours to wire.\n\nTHE CREDENTIAL COMES BACK ONCE. The connection string and password are in this response and nowhere else — every read beside it omits the password — so a caller that does not keep them has to provision again. Where KMS is configured the password is sealed there and only a reference is persisted; where it is not, it is returned this once and stored nowhere. It is never held in plaintext.\n\nScoped to the caller's validated org (403 without one), which also namespaces the physical resource under a fixed-width hash, so two tenants can never fold onto one backend resource — a residual collision fails closed with 409 rather than silently sharing. A name already taken in your org is 409; an invalid name or instance slug is 400; a backend that refuses the create is 502. Where a later step fails after the backend resource already exists, it is torn back down rather than left orphaned.\n\nBilling is gated BEFORE anything is created: an unfunded org — or, in the fail-closed default, an unreachable meter — gets the fleet-wide 402/503 and nothing is provisioned. The fee is per-kind and set by the deployment.", "tags": [ "datastore" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionRequest" } } } }, "responses": { "2XX": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionResult" } } } } } } }, "/v1/datastore/{name}": { "delete": { "operationId": "delete_v1_datastore_by_name", "summary": "Deprovisions one Hanzo Datastore warehouse.", "description": "Deprovisions one Hanzo Datastore warehouse. It reverts any app\ninstance bound to it back to Base BEFORE tearing down the org's dedicated\ninstance, then deletes the sealed credential and removes the metadata row.\nAnswers 204 with no body; a second call is a 404.", "tags": [ "datastore" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "warehouse" } ], "responses": { "204": { "description": "no content" } } }, "get": { "operationId": "get_v1_datastore_by_name", "summary": "Returns one Hanzo Datastore warehouse's metadata.", "description": "Returns one Hanzo Datastore warehouse's metadata. It carries the\nwarehouse's status, its instance address and the admin user the instance\nbooted with — never the password. A still-booting instance reads\n\"provisioning\", reconciled from the operator's live view rather than the row.", "tags": [ "datastore" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "warehouse" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionedResource" } } }, "description": "ok" } } } }, "/v1/docdb": { "get": { "operationId": "get_v1_docdb", "summary": "ListDocDB lists the caller org's Hanzo DocDB document databases.", "description": "ListDocDB lists the caller org's Hanzo DocDB document databases. Each one is\na DEDICATED FerretDB instance the org alone runs, speaking the MongoDB wire\nprotocol, so the host is that instance's own in-cluster Service and the port\nis 27017.", "tags": [ "docdb" ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/provisionedSummary" }, "type": "array" } } }, "description": "ok" } } }, "post": { "operationId": "post_v1_docdb", "summary": "Provision a document database for your org", "description": "Launches your org's OWN document-database instance — it speaks the MongoDB wire protocol, so existing MongoDB drivers connect unchanged — and answers with its `mongodb://` connection string. The instance is yours alone: a deployment in your own tenant namespace, so its admin credential is naturally scoped to you and no other tenant shares the process. Off-cluster, where there is no orchestrator to launch one, this fails closed with 503 rather than handing back a shared one.\n\n`name` is the org-unique slug every physical name derives from, and must match ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$. `instance` optionally BINDS the add-on to one of your app instances: the DSN is injected into that instance's addons secret as \u003cKIND\u003e_URL, switching the app off its built-in store and onto this one. Omit it and the connection string is yours to wire.\n\nTHE CREDENTIAL COMES BACK ONCE. The connection string and password are in this response and nowhere else — every read beside it omits the password — so a caller that does not keep them has to provision again. Where KMS is configured the password is sealed there and only a reference is persisted; where it is not, it is returned this once and stored nowhere. It is never held in plaintext.\n\nScoped to the caller's validated org (403 without one), which also namespaces the physical resource under a fixed-width hash, so two tenants can never fold onto one backend resource — a residual collision fails closed with 409 rather than silently sharing. A name already taken in your org is 409; an invalid name or instance slug is 400; a backend that refuses the create is 502. Where a later step fails after the backend resource already exists, it is torn back down rather than left orphaned.\n\nBilling is gated BEFORE anything is created: an unfunded org — or, in the fail-closed default, an unreachable meter — gets the fleet-wide 402/503 and nothing is provisioned. The fee is per-kind and set by the deployment.", "tags": [ "docdb" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionRequest" } } } }, "responses": { "2XX": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionResult" } } } } } } }, "/v1/docdb/{name}": { "delete": { "operationId": "delete_v1_docdb_by_name", "summary": "DropDocDB deprovisions one Hanzo DocDB database.", "description": "DropDocDB deprovisions one Hanzo DocDB database. It reverts any app instance\nbound to it back to Base BEFORE tearing down the org's dedicated FerretDB\ninstance, then deletes the sealed credential and removes the metadata row.\nAnswers 204 with no body; a second call is a 404.", "tags": [ "docdb" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "sessions" } ], "responses": { "204": { "description": "no content" } } }, "get": { "operationId": "get_v1_docdb_by_name", "summary": "GetDocDB returns one Hanzo DocDB database's metadata.", "description": "GetDocDB returns one Hanzo DocDB database's metadata. It carries the\ndatabase's status, its instance address and the SCRAM user the instance was\nset up with — never the password. A still-booting instance reads\n\"provisioning\", reconciled from the operator's live view.", "tags": [ "docdb" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "sessions" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionedResource" } } }, "description": "ok" } } } }, "/v1/kv": { "get": { "operationId": "get_v1_kv", "summary": "ListKV lists the caller org's Hanzo KV stores.", "description": "ListKV lists the caller org's Hanzo KV stores. Each one is a DEDICATED Valkey\ninstance the org alone runs, so the host is that instance's own in-cluster\nService and the port is 6379.", "tags": [ "kv" ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/provisionedSummary" }, "type": "array" } } }, "description": "ok" } } }, "post": { "operationId": "post_v1_kv", "summary": "Provision a key-value store for your org", "description": "Launches your org's OWN key-value instance and answers with its `kv://` connection string. The instance is yours alone: a deployment in your own tenant namespace, so its admin credential is naturally scoped to you and no other tenant shares the process. Off-cluster, where there is no orchestrator to launch one, this fails closed with 503 rather than handing back a shared one.\n\n`name` is the org-unique slug every physical name derives from, and must match ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$. `instance` optionally BINDS the add-on to one of your app instances: the DSN is injected into that instance's addons secret as \u003cKIND\u003e_URL, switching the app off its built-in store and onto this one. Omit it and the connection string is yours to wire.\n\nTHE CREDENTIAL COMES BACK ONCE. The connection string and password are in this response and nowhere else — every read beside it omits the password — so a caller that does not keep them has to provision again. Where KMS is configured the password is sealed there and only a reference is persisted; where it is not, it is returned this once and stored nowhere. It is never held in plaintext.\n\nScoped to the caller's validated org (403 without one), which also namespaces the physical resource under a fixed-width hash, so two tenants can never fold onto one backend resource — a residual collision fails closed with 409 rather than silently sharing. A name already taken in your org is 409; an invalid name or instance slug is 400; a backend that refuses the create is 502. Where a later step fails after the backend resource already exists, it is torn back down rather than left orphaned.\n\nBilling is gated BEFORE anything is created: an unfunded org — or, in the fail-closed default, an unreachable meter — gets the fleet-wide 402/503 and nothing is provisioned. The fee is per-kind and set by the deployment.", "tags": [ "kv" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionRequest" } } } }, "responses": { "2XX": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionResult" } } } } } } }, "/v1/kv/{name}": { "delete": { "operationId": "delete_v1_kv_by_name", "summary": "DropKV deprovisions one Hanzo KV store.", "description": "DropKV deprovisions one Hanzo KV store. It reverts any app instance bound to\nit back to Base BEFORE tearing down the org's dedicated Valkey instance, then\ndeletes the sealed credential and removes the metadata row. Answers 204 with\nno body; a second call is a 404.", "tags": [ "kv" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "sessions" } ], "responses": { "204": { "description": "no content" } } }, "get": { "operationId": "get_v1_kv_by_name", "summary": "GetKV returns one Hanzo KV store's metadata.", "description": "GetKV returns one Hanzo KV store's metadata. It carries the store's status,\nits instance address and the Valkey user it authenticates as (\"default\", the\nonly user a requirepass instance has) — never the password. A still-booting\ninstance reads \"provisioning\", reconciled from the operator's live view.", "tags": [ "kv" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "sessions" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionedResource" } } }, "description": "ok" } } } }, "/v1/s3": { "get": { "operationId": "get_v1_s3", "summary": "Lists the caller org's object-storage buckets.", "description": "Lists the caller org's object-storage buckets. A bucket lives in an\nalready-live shared object store and is reached through the public gateway.\nThe names here are the friendly ones the org provisioned; the physical bucket\nis org-namespaced underneath, which is what keeps two tenants' buckets\ndistinct.", "tags": [ "s3" ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/provisionedSummary" }, "type": "array" } } }, "description": "ok" } } }, "post": { "operationId": "post_v1_s3", "summary": "Provision an object storage bucket for your org", "description": "Creates an S3-compatible bucket inside the already-running shared object store and answers with the endpoint that reaches it.\n\n`name` is the org-unique slug every physical name derives from, and must match ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$. `instance` optionally BINDS the add-on to one of your app instances: the DSN is injected into that instance's addons secret as \u003cKIND\u003e_URL, switching the app off its built-in store and onto this one. Omit it and the connection string is yours to wire.\n\nTHE CREDENTIAL COMES BACK ONCE. The connection string and password are in this response and nowhere else — every read beside it omits the password — so a caller that does not keep them has to provision again. Where KMS is configured the password is sealed there and only a reference is persisted; where it is not, it is returned this once and stored nowhere. It is never held in plaintext.\n\nScoped to the caller's validated org (403 without one), which also namespaces the physical resource under a fixed-width hash, so two tenants can never fold onto one backend resource — a residual collision fails closed with 409 rather than silently sharing. A name already taken in your org is 409; an invalid name or instance slug is 400; a backend that refuses the create is 502. Where a later step fails after the backend resource already exists, it is torn back down rather than left orphaned.\n\nBilling is gated BEFORE anything is created: an unfunded org — or, in the fail-closed default, an unreachable meter — gets the fleet-wide 402/503 and nothing is provisioned. The fee is per-kind and set by the deployment.", "tags": [ "s3" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionRequest" } } } }, "responses": { "2XX": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionResult" } } } } } } }, "/v1/s3/{name}": { "delete": { "operationId": "delete_v1_s3_by_name", "summary": "Deletes one bucket from the shared object store and removes its metadata row.", "description": "Deletes one bucket from the shared object store and removes its\nmetadata row. Answers 204 with no body; a second call is a 404.", "tags": [ "s3" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "uploads" } ], "responses": { "204": { "description": "no content" } } }, "get": { "operationId": "get_v1_s3_by_name", "summary": "Returns one bucket's metadata.", "description": "Returns one bucket's metadata. It carries the bucket's status and the\ngateway address it is reached at, and no username: the object store\nauthenticates with a shared, out-of-band key rather than a per-bucket\ncredential.", "tags": [ "s3" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "uploads" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionedResource" } } }, "description": "ok" } } } }, "/v1/search": { "get": { "operationId": "get_v1_search", "summary": "Lists the caller org's search indexes.", "description": "Lists the caller org's search indexes. An index is a logical\nresource inside an already-live shared backend, so every one of them is\nreached through the public gateway rather than at an instance of its own.", "tags": [ "search" ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/provisionedSummary" }, "type": "array" } } }, "description": "ok" } } }, "post": { "operationId": "post_v1_search", "summary": "Provision a search index for your org", "description": "Creates a search index inside the already-running shared search backend and answers with the endpoint that reaches it.\n\n`name` is the org-unique slug every physical name derives from, and must match ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$. `instance` optionally BINDS the add-on to one of your app instances: the DSN is injected into that instance's addons secret as \u003cKIND\u003e_URL, switching the app off its built-in store and onto this one. Omit it and the connection string is yours to wire.\n\nTHE CREDENTIAL COMES BACK ONCE. The connection string and password are in this response and nowhere else — every read beside it omits the password — so a caller that does not keep them has to provision again. Where KMS is configured the password is sealed there and only a reference is persisted; where it is not, it is returned this once and stored nowhere. It is never held in plaintext.\n\nScoped to the caller's validated org (403 without one), which also namespaces the physical resource under a fixed-width hash, so two tenants can never fold onto one backend resource — a residual collision fails closed with 409 rather than silently sharing. A name already taken in your org is 409; an invalid name or instance slug is 400; a backend that refuses the create is 502. Where a later step fails after the backend resource already exists, it is torn back down rather than left orphaned.\n\nBilling is gated BEFORE anything is created: an unfunded org — or, in the fail-closed default, an unreachable meter — gets the fleet-wide 402/503 and nothing is provisioned. The fee is per-kind and set by the deployment.", "tags": [ "search" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionRequest" } } } }, "responses": { "2XX": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionResult" } } } } } } }, "/v1/search/{name}": { "delete": { "operationId": "delete_v1_search_by_name", "summary": "Deletes one search index from the shared backend and removes its metadata row.", "description": "Deletes one search index from the shared backend and removes its\nmetadata row. Answers 204 with no body; a second call is a 404.", "tags": [ "search" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "products" } ], "responses": { "204": { "description": "no content" } } }, "get": { "operationId": "get_v1_search_by_name", "summary": "Returns one search index's metadata.", "description": "Returns one search index's metadata. It carries the index's status\nand the gateway address it is reached at, and no username: the backend\nauthenticates with a shared, out-of-band key rather than a per-index\ncredential.", "tags": [ "search" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "products" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionedResource" } } }, "description": "ok" } } } }, "/v1/sql": { "get": { "operationId": "get_v1_sql", "summary": "ListSQL lists the caller org's Hanzo SQL databases.", "description": "ListSQL lists the caller org's Hanzo SQL databases. Each one is a DEDICATED\nPostgreSQL instance the org alone runs, so the host is that instance's own\nin-cluster Service and the port is 5432.", "tags": [ "sql" ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/provisionedSummary" }, "type": "array" } } }, "description": "ok" } } }, "post": { "operationId": "post_v1_sql", "summary": "Provision a PostgreSQL database for your org", "description": "Launches your org's OWN PostgreSQL instance and answers with its `postgres://` connection string. The instance is yours alone: a deployment in your own tenant namespace, so its admin credential is naturally scoped to you and no other tenant shares the process. Off-cluster, where there is no orchestrator to launch one, this fails closed with 503 rather than handing back a shared one.\n\n`name` is the org-unique slug every physical name derives from, and must match ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$. `instance` optionally BINDS the add-on to one of your app instances: the DSN is injected into that instance's addons secret as \u003cKIND\u003e_URL, switching the app off its built-in store and onto this one. Omit it and the connection string is yours to wire.\n\nTHE CREDENTIAL COMES BACK ONCE. The connection string and password are in this response and nowhere else — every read beside it omits the password — so a caller that does not keep them has to provision again. Where KMS is configured the password is sealed there and only a reference is persisted; where it is not, it is returned this once and stored nowhere. It is never held in plaintext.\n\nScoped to the caller's validated org (403 without one), which also namespaces the physical resource under a fixed-width hash, so two tenants can never fold onto one backend resource — a residual collision fails closed with 409 rather than silently sharing. A name already taken in your org is 409; an invalid name or instance slug is 400; a backend that refuses the create is 502. Where a later step fails after the backend resource already exists, it is torn back down rather than left orphaned.\n\nBilling is gated BEFORE anything is created: an unfunded org — or, in the fail-closed default, an unreachable meter — gets the fleet-wide 402/503 and nothing is provisioned. The fee is per-kind and set by the deployment.", "tags": [ "sql" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionRequest" } } } }, "responses": { "2XX": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionResult" } } } } } } }, "/v1/sql/{name}": { "delete": { "operationId": "delete_v1_sql_by_name", "summary": "DropSQL deprovisions one Hanzo SQL database.", "description": "DropSQL deprovisions one Hanzo SQL database. It reverts any app instance\nbound to it back to Base BEFORE tearing down the org's dedicated Postgres\ninstance — never a live app pointed at a deleted backend — then deletes the\nsealed credential and removes the metadata row. Answers 204 with no body; a\nsecond call is a 404, not a second delete.", "tags": [ "sql" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "orders" } ], "responses": { "204": { "description": "no content" } } }, "get": { "operationId": "get_v1_sql_by_name", "summary": "GetSQL returns one Hanzo SQL database's metadata.", "description": "GetSQL returns one Hanzo SQL database's metadata. It carries the database's\nstatus, its instance address and the admin user Postgres booted with — never\nthe password, which is returned once at create and otherwise lives only in\nHanzo KMS. A still-booting instance reads \"provisioning\", reconciled from the\noperator's live view rather than from the row.", "tags": [ "sql" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "orders" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionedResource" } } }, "description": "ok" } } } }, "/v1/vector": { "get": { "operationId": "get_v1_vector", "summary": "Lists the caller org's vector collections.", "description": "Lists the caller org's vector collections. A collection is a\nlogical resource inside an already-live shared backend, so every one of them\nis reached through the public gateway rather than at an instance of its own.", "tags": [ "vector" ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/provisionedSummary" }, "type": "array" } } }, "description": "ok" } } }, "post": { "operationId": "post_v1_vector", "summary": "Provision a vector collection for your org", "description": "Creates a vector collection inside the already-running shared vector backend and answers with the endpoint that reaches it.\n\n`name` is the org-unique slug every physical name derives from, and must match ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$. `instance` optionally BINDS the add-on to one of your app instances: the DSN is injected into that instance's addons secret as \u003cKIND\u003e_URL, switching the app off its built-in store and onto this one. Omit it and the connection string is yours to wire.\n\nTHE CREDENTIAL COMES BACK ONCE. The connection string and password are in this response and nowhere else — every read beside it omits the password — so a caller that does not keep them has to provision again. Where KMS is configured the password is sealed there and only a reference is persisted; where it is not, it is returned this once and stored nowhere. It is never held in plaintext.\n\nScoped to the caller's validated org (403 without one), which also namespaces the physical resource under a fixed-width hash, so two tenants can never fold onto one backend resource — a residual collision fails closed with 409 rather than silently sharing. A name already taken in your org is 409; an invalid name or instance slug is 400; a backend that refuses the create is 502. Where a later step fails after the backend resource already exists, it is torn back down rather than left orphaned.\n\nBilling is gated BEFORE anything is created: an unfunded org — or, in the fail-closed default, an unreachable meter — gets the fleet-wide 402/503 and nothing is provisioned. The fee is per-kind and set by the deployment.", "tags": [ "vector" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionRequest" } } } }, "responses": { "2XX": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionResult" } } } } } } }, "/v1/vector/{name}": { "delete": { "operationId": "delete_v1_vector_by_name", "summary": "Deletes one vector collection from the shared backend and removes its metadata row.", "description": "Deletes one vector collection from the shared backend and removes\nits metadata row. Answers 204 with no body; a second call is a 404.", "tags": [ "vector" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "embeddings" } ], "responses": { "204": { "description": "no content" } } }, "get": { "operationId": "get_v1_vector_by_name", "summary": "Returns one vector collection's metadata.", "description": "Returns one vector collection's metadata. It carries the\ncollection's status and the gateway address it is reached at, and no username:\nthe backend authenticates with a shared, out-of-band key rather than a\nper-collection credential, so there is no per-resource user to report.", "tags": [ "vector" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Name is the resource's org-unique slug, from the path. Lower-cased and\ntrimmed before lookup, exactly as it was at create.", "schema": { "type": "string" }, "example": "embeddings" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/provisionedResource" } } }, "description": "ok" } } } } }, "components": { "schemas": { "provisionRequest": { "type": "object", "properties": { "instance": { "type": "string" }, "name": { "type": "string" } } }, "provisionResult": { "type": "object", "properties": { "connectionString": { "type": "string" }, "database": { "type": "string" }, "host": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" }, "port": { "type": "integer" }, "status": { "type": "string" }, "username": { "type": "string" } } }, "provisionedResource": { "properties": { "database": { "description": "Database is the logical database, collection, index or bucket this\nresource resolves to on its backend.", "type": "string" }, "host": { "description": "Host is the address that actually routes to this resource — a dedicated\ninstance's own in-cluster Service, or the public gateway for a shared one.", "type": "string" }, "id": { "description": "ID is the resource's server-minted handle, \"rs_\"-prefixed.", "type": "string" }, "kind": { "description": "Kind is the product: sql, vector, datastore, kv, search, s3 or docdb.", "type": "string" }, "name": { "description": "Name is the org-unique slug the caller provisioned the resource under.", "type": "string" }, "port": { "description": "Port is the port a client connects to on Host.", "type": "integer" }, "status": { "description": "Status is \"ready\", or \"provisioning\" while a dedicated instance is still\nbeing materialized. A dedicated resource's status is reconciled from the\noperator's live CR before this is answered, so it is never a stale ready.", "type": "string" }, "username": { "description": "Username is the credential's user, for the kinds that mint one per\nresource. Absent for a kind whose backend authenticates with a shared,\nout-of-band key.", "type": "string" } }, "type": "object" }, "provisionedSummary": { "properties": { "createdAt": { "description": "CreatedAt is when the resource was provisioned, in unix seconds.", "type": "integer" }, "host": { "description": "Host is the address that actually routes to this resource — a dedicated\ninstance's own in-cluster Service, or the public gateway for a shared one.\nNever the internal admin address of a shared backend.", "type": "string" }, "id": { "description": "ID is the resource's server-minted handle, \"rs_\"-prefixed.", "type": "string" }, "kind": { "description": "Kind is the product: sql, vector, datastore, kv, search, s3 or docdb.", "type": "string" }, "name": { "description": "Name is the org-unique slug the caller provisioned the resource under.", "type": "string" }, "port": { "description": "Port is the port a client connects to on Host.", "type": "integer" }, "status": { "description": "Status is \"ready\", or \"provisioning\" while a dedicated instance is still\nbeing materialized by the operator.", "type": "string" } }, "type": "object" } } } }