Skip to main content
PATCH/storage/locations/{locationId}

Update Storage Location

Updates a storage location.

Rotating its credential is always allowed.

Moving a location that a bucket or dataset uses (changing its bucket, region or endpoint) is refused with 409 K9O_STATE_CONFLICT, reason location_in_use, because it would silently re-point objects already written there.

A region outside the project's residency set is refused.

The change is audited as data.write.org.settings_updated.

Parameters
locationId *path

The storage location's id (byos_...).

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
bucketNamestring

The new bucket name.

Refused with 409 while a bucket or Dataset uses the location.

regionstring

The new platform region; it must be in the project's residency set.

Refused with 409 while the location is in use.

providerRegionstring

The new provider region.

Refused with 409 while the location is in use.

endpointOverrideany

The new endpoint URL, or null to clear it.

Refused with 409 while the location is in use.

One of: string
or: null
credentialRefstring

A new credential reference, kibo://byos-creds/sec_....

Rotating the credential is allowed while the location is in use.

custodyMode"PLATFORM_MANAGED" | "BYOK" | "HYOK"

The new custody mode.

Refused with 409 while the location is in use.

providerParamsobject

Non-secret settings the provider's credential exchange needs, as string keys with string values (each value at most 512 characters, at most 16 keys).

The keys read per provider:

  • r2 needs accountId and parentAccessKeyId.
  • b2 needs bucketId.
  • gcs needs serviceAccountEmail.
  • azure_blob needs azureTenantId.
  • s3, s3_compatible and minio read none.

Never put a secret here: the secret lives in the credential that credentialRef names, and these values are returned as stored on every read.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEThe updated credentialRef is not a valid kibo://byos-creds/<secId> reference; pre-create the credential secret and bind its reference.
403K9O_ACCESS_DENIEDYour role does not permit updating this storage location.
403K9O_CREDENTIAL_CUSTODY_MISMATCHThe requested credential access mode does not match the custody mode configured for this project.
404K9O_NOT_FOUNDNo storage location with this id exists in the project, or it is retired.
409K9O_STATE_CONFLICTThe change would move a storage location that a bucket or a Dataset still uses (`context.reason: "location_in_use"`, with the buckets and the Dataset count). A change to `bucketName`, `region`, `endpointOverride`, `providerParams` or `custodyMode` is a move; rotating `credentialRef` is not.
Response body (200)
data *object

A storage location: a bucket at an outside provider that the project's storage writes to.

id *string

The location id (byos_...).

projectId *string

The project the location belongs to (proj_...).

provider *"s3" | "s3_compatible" | "gcs" | "azure_blob" | "minio" | "r2" | "b2"

The storage provider. s3_compatible is any S3 API at endpointOverride.

bucketName *string

The bucket or container name at the provider.

region *string

The platform region the data belongs to.

providerRegion *string

The bucket's region at its provider.

endpointOverride *any

The custom endpoint URL, or null when none is set.

One of: string
or: null
credentialRef *string

The credential reference (kibo://byos-creds/sec_...).

The secret itself is never returned.

custodyMode *"PLATFORM_MANAGED" | "BYOK" | "HYOK"

Who holds the encryption keys for data written to the location.

providerParams *object

The non-secret provider settings as stored, string keys with string values; an empty object when none were given.

createdAt *string <date-time>

When the location was created.

retiredAt *any

When the location was retired, or null while it is active.

List results are always active; a read by id also returns a retired location.

One of: string <date-time>
or: null
meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.storage.locations.update('<locationId>', {})

Showing example in TypeScript

Request example
{
  "bucketName": "string",
  "region": "string",
  "providerRegion": "string",
  "endpointOverride": "string",
  "credentialRef": "string",
  "custodyMode": "PLATFORM_MANAGED"
}
Response example (200)
{
  "data": {
    "id": "string",
    "projectId": "string",
    "provider": "s3",
    "bucketName": "string",
    "region": "string",
    "providerRegion": "string",
    "endpointOverride": "string",
    "credentialRef": "string",
    "custodyMode": "PLATFORM_MANAGED",
    "createdAt": "string",
    "retiredAt": "string"
  }
}

More in Storage & Schema