Create database binding API Reference

POST

/tenants/{tenant}/databases/{name}/bindings

curl --request POST \
  --url https://api.kupe.cloud/api/v1/tenants/acme/databases/orders-db/bindings \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "cluster": "prod", "name": "orders-db-prod-readwrite", "namespaces": [ "orders-api", "orders-worker" ], "role": "owner", "secretName": "orders-db-readwrite" }'

Authorizations

• BearerAuth

Parameters

Path Parameters

tenant

required

string

Tenant name

name

required

string

Database name

Request Body

Binding configuration

Media type application/json

object

cluster

Cluster to bind into. It may not exist yet; the binding stays Pending until it does.

string

Example

prod

name

Binding name (DNS-safe, 1-63 characters)

string

Example

orders-db-prod-readwrite

namespaces

Namespaces inside the cluster that receive the Service and credentials Secret: 1 to 10, each listed once, none kube-* or argocd. PATCH the binding to add or remove namespaces.

Array<string>

Example

[
  "orders-api",
  "orders-worker"
]

role

Role granted: owner (changes the schema), readwrite (reads and writes data) or readonly (reads data).

string

Allowed values: owner readwrite readonly

Example

readwrite

secretName

Name of the credentials Secret in every listed namespace. Defaults to “{database}-{role}”, e.g. “orders-db-readwrite”.

string

Example

orders-db-readwrite

Responses

201

Binding created

Media type application/json

object

cluster

string

createdAt

string

database

string

name

string

namespaces

Namespaces are the namespaces the binding delivers into (1 to 10).

Array<string>

resourceVersion

string

role

string

Allowed values: owner readwrite readonly

secretName

SecretName as requested; empty means the default “{database}-{role}”.

string

status

object

conditions

Array<object>

object

key

additional properties

message

string

namespaces

Namespaces reports what was delivered into each namespace. A namespace removed from namespaces stays here until what was delivered there is withdrawn.

Array<object>

object

deliveredRotation

DeliveredRotation is the rotate-credentials token of the password the credentials Secret in this namespace carries; empty if the role was never rotated.

string

host

Host is the in-cluster DNS name applications in this namespace connect to; empty while nothing is delivered.

string

message

Message gives detail while the namespace is not Ready.

string

name

Name is the namespace inside the cluster.

string

phase

string

Allowed values: Pending Ready Failed

phase

Phase is Ready only when every listed namespace is Ready.

string

Allowed values: Pending Ready Failed

secretName

SecretName is the effective credentials Secret name in every listed namespace.

string

Example

{
  "cluster": "prod",
  "createdAt": "2026-10-09T10:05:00Z",
  "database": "orders-db",
  "name": "orders-db-prod-readwrite",
  "namespaces": [
    "orders-api",
    "orders-worker"
  ],
  "resourceVersion": "582020",
  "role": "owner",
  "secretName": "orders-db-readwrite",
  "status": {
    "message": "",
    "namespaces": [
      {
        "deliveredRotation": "2026-10-09T12:00:00.123456789Z",
        "host": "orders-db.orders-api.svc.cluster.local",
        "message": "",
        "name": "orders-api",
        "phase": "Pending"
      }
    ],
    "phase": "Pending",
    "secretName": "orders-db-readwrite"
  }
}

Headers

ETag

string

Resource version

400

Validation error

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

401

Missing or invalid authentication

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

403

Admin access required

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

404

Database not found, or databases are not enabled (code databases_unavailable)

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

409

Binding name already exists, or the database is being deleted (code terminating)

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

429

Rate limit exceeded

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}