API reference

Storage

Browse and manage S3 buckets: files, uploads, CORS, versioning and lifecycle rules.

These routes back the file browser in Cloud. Uploads and downloads go straight to S3 through short-lived links; the API never handles file bodies. See Buckets.

`GET /v1/orgs/:orgId/storage`

The org's buckets with their latest daily size and object count.

Auth: user access token or platform agent key · Scope: resources:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  buckets: {
    usage: null | {
      sizeBytes?: number
      objects?: number
      at?: number
    }
    type: "repository" | "database" | "bucket"
    name: string
    status?: "error" | "active" | "creating" | "deleting"
    createdAt?: number
    updatedAt?: number
    region: string
    orgId: string
    createdBy: string
    projectId?: string
    location: string
    resourceId: string
    arn?: string
    physicalName: string
  }[]
}

`GET /v1/orgs/:orgId/storage/:resourceId`

A bucket record with its versioning status and latest daily usage.

Auth: user access token or platform agent key · Scope: resources:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Response 200

{
  bucket: {
    type: "repository" | "database" | "bucket"
    name: string
    status?: "error" | "active" | "creating" | "deleting"
    createdAt?: number
    updatedAt?: number
    region: string
    orgId: string
    createdBy: string
    projectId?: string
    location: string
    resourceId: string
    arn?: string
    physicalName: string
  }
  versioning: null | "Enabled" | "Suspended" | "Disabled"
  usage: null | {
    sizeBytes?: number
    objects?: number
    at?: number
  }
}

Errors

Status	Message
`404`	Bucket not found

Errors from AWS are mapped as in AWS errors.

`GET /v1/orgs/:orgId/storage/:resourceId/objects`

One level of the bucket: folders (common prefixes) and files under prefix.

Auth: user access token or platform agent key · Scope: resources:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Query parameter	Type	Required	Default	Notes
`prefix`	`string`	No	`""`	up to 1,024 characters
`cursor`	`string`	No		up to 2,048 characters
`limit`	`integer`	No	`100`	≥ 1; coerced from a string

Response 200

{
  prefix: string
  folders: string[]
  files: {
    key: string
    size: number
    lastModified?: number
    etag?: string
    storageClass: "AWS_BACKUP_LOW_COST_WARM" | "AWS_BACKUP_WARM" | "DEEP_ARCHIVE" | "EXPRESS_ONEZONE" | "FSX_ONTAP" | "FSX_OPENZFS" | "GLACIER" | "GLACIER_IR" | "INTELLIGENT_TIERING" | "ONEZONE_IA" | "OUTPOSTS" | "REDUCED_REDUNDANCY" | "SNOW" | "STANDARD" | "STANDARD_IA"
  }[]
  cursor?: string
}

Errors

Status	Message
`400`	Folder paths end with /.
`404`	Bucket not found

Errors from AWS are mapped as in AWS errors.

`GET /v1/orgs/:orgId/storage/:resourceId/object`

One file's size, type, modification time and metadata.

Auth: user access token or platform agent key · Scope: resources:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Query parameter	Type	Required	Notes
`key`	`string`	Yes	up to 1,024 characters

Response 200

{
  object: {
    key: string
    size: number
    contentType?: string
    lastModified?: number
    etag?: string
    storageClass: "AWS_BACKUP_LOW_COST_WARM" | "AWS_BACKUP_WARM" | "DEEP_ARCHIVE" | "EXPRESS_ONEZONE" | "FSX_ONTAP" | "FSX_OPENZFS" | "GLACIER" | "GLACIER_IR" | "INTELLIGENT_TIERING" | "ONEZONE_IA" | "OUTPOSTS" | "REDUCED_REDUNDANCY" | "SNOW" | "STANDARD" | "STANDARD_IA"
    versionId?: string
    cacheControl?: string
    contentEncoding?: string
    contentDisposition?: string
    encryption?: "AES256" | "aws:backup" | "aws:fsx" | "aws:kms" | "aws:kms:dsse"
    metadata: {
      [key: string]: string
    }
  }
}

Errors

Status	Message
`404`	Bucket not found

Errors from AWS are mapped as in AWS errors.

`GET /v1/orgs/:orgId/storage/:resourceId/download`

A download link valid for five minutes.

Auth: user access token or platform agent key · Scope: resources:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Query parameter	Type	Required	Notes
`key`	`string`	Yes	up to 1,024 characters

Response 200

{
  url: string
  expiresIn: number
}

Errors

Status	Message
`400`	Folders can't be downloaded.
`404`	Bucket not found

Errors from AWS are mapped as in AWS errors.

`POST /v1/orgs/:orgId/storage/:resourceId/uploads`

Upload links (PUT, 15 minutes, up to 5 GB each). The browser sends each file straight to S3.

Auth: user access token or platform agent key · Scope: resources:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Request body

Field	Type	Required	Notes
`files`	`object[]`	Yes	at least 1 item
`files[].key`	`string`	Yes	up to 1,024 characters
`files[].contentType`	`string \| ""`	Yes	up to 255 characters; matches `^[\w.+-]+\/[\w.+-]+(\s;.)?$`
`files[].size`	`integer`	Yes	≥ 0

Response 200

{
  uploads: {
    key: string
    url: string
    contentType: string
  }[]
  expiresIn: number
}

Errors

Status	Message
`400`	File names can't end with /.
`404`	Bucket not found
`413`	… is larger than 5 GB.

Errors from AWS are mapped as in AWS errors.

`POST /v1/orgs/:orgId/storage/:resourceId/folders`

Creates an empty folder under prefix.

Auth: user access token or platform agent key · Scope: resources:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Request body

Field	Type	Required	Default	Notes
`prefix`	`string`	No	`""`	up to 1,024 characters
`name`	`string`	Yes		1–255 characters

Response 201

{
  key: string
}

Errors

Status	Message
`400`	Folder paths end with /.
`400`	Folder names can't contain /.
`404`	Bucket not found

Errors from AWS are mapped as in AWS errors.

`POST /v1/orgs/:orgId/storage/:resourceId/objects/delete`

Deletes files and folders (with everything in them). done: false means call again to finish large folders.

Auth: user access token or platform agent key · Scope: resources:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Request body

Field	Type	Required	Default	Notes
`keys`	`string[]`	No	`[]`	each up to 1,024 characters
`prefixes`	`string[]`	No	`[]`	up to 100 items; each up to 1,024 characters

Also checked: Nothing to delete.

Response 200

{
  deleted: number
  done: boolean
}

Errors

Status	Message
`400`	Pick folders to delete, not the whole bucket.
`400`	Folder paths end with /.
`404`	Bucket not found
`409`	Couldn't delete … file…: …

Errors from AWS are mapped as in AWS errors.

`GET /v1/orgs/:orgId/storage/:resourceId/settings`

CORS rules, versioning and lifecycle rules.

Auth: user access token or platform agent key · Scope: resources:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Response 200

{
  versioning: string
  cors: {
    ID?: string
    AllowedHeaders?: string[]
    AllowedMethods?: string[]
    AllowedOrigins?: string[]
    ExposeHeaders?: string[]
    MaxAgeSeconds?: number
  }[]
  cloudCors: {
    ID?: string
    AllowedHeaders?: string[]
    AllowedMethods?: string[]
    AllowedOrigins?: string[]
    ExposeHeaders?: string[]
    MaxAgeSeconds?: number
  }
  lifecycle: {
    id: string
    prefix: string
    enabled: boolean
    expirationDays?: number
    noncurrentDays?: number
    other: boolean
  }[]
  publicAccessBlocked: boolean
}

Errors

Status	Message
`404`	Bucket not found

Errors from AWS are mapped as in AWS errors.

`PUT /v1/orgs/:orgId/storage/:resourceId/cors`

Replaces the bucket's CORS rules (Cloud's upload rule is kept separately).

Auth: user access token or platform agent key · Scope: resources:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Request body

Field	Type	Required	Notes
`rules`	`object[]`	Yes
`rules[].ID`	`string`	No	up to 255 characters
`rules[].AllowedOrigins`	`string[]`	Yes	1–50 items; each 1–255 characters
`rules[].AllowedMethods`	`("GET" \| "PUT" \| "POST" \| "DELETE" \| "HEAD")[]`	Yes	at least 1 item
`rules[].AllowedHeaders`	`string[]`	No	up to 50 items; each 1–255 characters
`rules[].ExposeHeaders`	`string[]`	No	up to 50 items; each 1–255 characters
`rules[].MaxAgeSeconds`	`integer`	No	0–604800

Response 200

{
  cors: {
    AllowedOrigins: string[]
    AllowedMethods: ("GET" | "PUT" | "POST" | "DELETE" | "HEAD")[]
    ID?: string
    AllowedHeaders?: string[]
    ExposeHeaders?: string[]
    MaxAgeSeconds?: number
  }[]
}

Errors

Status	Message
`400`	si-cloud-uploads is reserved for Cloud uploads.
`404`	Bucket not found

Errors from AWS are mapped as in AWS errors.

`PUT /v1/orgs/:orgId/storage/:resourceId/versioning`

Turns versioning on, or suspends it.

Auth: user access token or platform agent key · Scope: resources:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Request body

Field	Type	Required	Notes
`enabled`	`boolean`	Yes

Response 200

{
  versioning: string
}

Errors

Status	Message
`404`	Bucket not found

Errors from AWS are mapped as in AWS errors.

`POST /v1/orgs/:orgId/storage/:resourceId/lifecycle`

Adds a rule that deletes files under a prefix a number of days after they're written.

Auth: user access token or platform agent key · Scope: resources:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Request body

Field	Type	Required	Default	Notes
`prefix`	`string`	No	`""`	up to 1,024 characters
`days`	`integer`	Yes		1–3650
`noncurrentDays`	`integer`	No		1–3650

Response 201

{
  rule: {
    id: string
    prefix: string
    enabled: boolean
    expirationDays?: number
    noncurrentDays?: number
    other: boolean
  }
  lifecycle: {
    id: string
    prefix: string
    enabled: boolean
    expirationDays?: number
    noncurrentDays?: number
    other: boolean
  }[]
}

Errors

Status	Message
`404`	Bucket not found
`409`	A bucket can have 50 rules here.

Errors from AWS are mapped as in AWS errors.

`DELETE /v1/orgs/:orgId/storage/:resourceId/lifecycle/:ruleId`

Removes a lifecycle rule.

Auth: user access token or platform agent key · Scope: resources:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).
`:ruleId`	Lifecycle rule id, as returned by the settings or lifecycle routes.

Response 200

{
  lifecycle: {
    id: string
    prefix: string
    enabled: boolean
    expirationDays?: number
    noncurrentDays?: number
    other: boolean
  }[]
}

Errors

Status	Message
`404`	Bucket not found
`404`	Rule not found

Errors from AWS are mapped as in AWS errors.

`DELETE /v1/orgs/:orgId/storage/:resourceId`

Deletes an empty bucket (old versions of deleted files go with it) and its record.

Auth: user access token or platform agent key · Scope: resources:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).

Response 204 with no body.

Errors

Status	Message
`404`	Bucket not found
`409`	Delete every file in this bucket first.
`409`	Still removing old file versions. Try again to continue.
`409`	Couldn't delete … file…: …
`409`	Files were added while deleting. Delete them first.

Errors from AWS are mapped as in AWS errors.

Storage

On this page