Storage

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

Response 200

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

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

Response 200

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

Errors

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

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

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

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

Errors from AWS are mapped as in AWS errors.

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

A download link valid for five minutes. versionId downloads an earlier version.

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

Response 200

{
  url: string
  expiresIn: number
}

Errors

Errors from AWS are mapped as in AWS errors.

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

Every version and delete marker of one file, newest first (versioned buckets).

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

Response 200

{
  key: string
  versions: {
    versionId: string
    isLatest: boolean
    deleteMarker: boolean
    lastModified?: number
    size?: number
    etag?: string
  }[]
  truncated: boolean
}

Errors

Errors from AWS are mapped as in AWS errors.

POST /v1/orgs/:orgId/storage/:resourceId/object/restore

Makes an earlier version of a file current again (copied on top, so history is kept). With the newest delete marker of a deleted file, removes the marker and so brings the file back.

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

Request body

Response 200

{
  restored: "undeleted"
} | {
  restored: "copied"
}

Errors

Errors from AWS are mapped as in AWS errors.

POST /v1/orgs/:orgId/storage/:resourceId/object/versions/delete

Deletes one version of a file for good; its other versions stay.

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

Request body

Response 204 with no body.

Errors

Errors from AWS are mapped as in AWS errors.

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

Deleted files in one folder of a versioned bucket (their newest version is a delete marker).

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

Response 200

{
  prefix: string
  files: {
    key: string
    deletedAt?: number
    versionId: string
  }[]
  cursor?: string
}

Errors

Errors from AWS are mapped as in AWS errors.

POST /v1/orgs/:orgId/storage/:resourceId/objects/move

Moves or renames files and folders (copy, then delete the original); never overwrites. Folders move in batches: done: false means call again with the same moves and resume: true.

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

Request body

Also checked: Nothing to move.

Response 200

{
  moved: number
  done: boolean
}

Errors

Errors from AWS are mapped as in AWS errors.

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

Starts a multipart upload for a large file (up to 5 TB): the part size and how many parts to send.

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

Request body

Response 201

{
  key: string
  uploadId: string
  partSize: number
  parts: number
  contentType: string
}

Errors

Errors from AWS are mapped as in AWS errors.

POST /v1/orgs/:orgId/storage/:resourceId/uploads/multipart/parts

Upload links (15 minutes) for parts of a multipart upload; the browser PUTs each part and keeps its ETag.

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

Request body

Response 200

{
  urls: {
    partNumber: number
    url: string
  }[]
  expiresIn: number
}

Errors

Errors from AWS are mapped as in AWS errors.

POST /v1/orgs/:orgId/storage/:resourceId/uploads/multipart/complete

Finishes a multipart upload from its parts' numbers and ETags.

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

Request body

Response 200

{
  key: string
}

Errors

Errors from AWS are mapped as in AWS errors.

POST /v1/orgs/:orgId/storage/:resourceId/uploads/multipart/abort

Cancels a multipart upload and discards the parts sent so far.

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

Request body

Response 204 with no body.

Errors

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

Request body

Response 200

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

Errors

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

Request body

Response 201

{
  key: string
}

Errors

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

Request body

Also checked: Nothing to delete.

Response 200

{
  deleted: number
  done: boolean
}

Errors

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

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
  }[]
  abortUploadsDays?: number
  publicAccessBlocked: boolean
}

Errors

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

Request body

Response 200

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

Errors

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

Request body

Response 200

{
  versioning: string
}

Errors

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

Request body

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

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

Response 200

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

Errors

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

Response 204 with no body.

Errors

Errors from AWS are mapped as in AWS errors.