API reference

Databases

Browse and edit DynamoDB tables: items, indexes, metrics and settings.

These routes back the database explorer in Cloud. Each one works on a table the organization owns, found by its resource id; reads need resources:read and changes resources:write. See Databases.

`GET /v1/orgs/:orgId/databases`

The org's databases with live status, item count and size from DynamoDB.

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

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

Response 200

{
  databases: {
    table: {
      status: string
      itemCount: number
      sizeBytes: number
      partitionKey: {
        name: string
        type: "S" | "N" | "B"
      }
      sortKey?: {
        name: string
        type: "S" | "N" | "B"
      }
      indexCount: number
      deletionProtection: boolean
    }
    type: "repository" | "database" | "bucket"
    name: string
    status?: "error" | "active" | "creating" | "deleting"
    createdAt?: number
    updatedAt?: number
    region: string
    orgId: string
    resourceId: string
    createdBy: string
    projectId?: string
    location: string
    arn?: string
    physicalName: string
  } | {
    table: null
    error: "unavailable" | "missing"
    type: "repository" | "database" | "bucket"
    name: string
    status?: "error" | "active" | "creating" | "deleting"
    createdAt?: number
    updatedAt?: number
    region: string
    orgId: string
    resourceId: string
    createdBy: string
    projectId?: string
    location: string
    arn?: string
    physicalName: string
  }[]
}

Errors

Status	Message
`404`	Table not found

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

A database record and its live table description (keys, indexes, status). table is null when the table was deleted outside the platform.

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

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

Response 200

{
  database: {
    type: "repository" | "database" | "bucket"
    name: string
    status?: "error" | "active" | "creating" | "deleting"
    createdAt?: number
    updatedAt?: number
    region: string
    orgId: string
    resourceId: string
    createdBy: string
    projectId?: string
    location: string
    arn?: string
    physicalName: string
  }
  table: {
    partitionKey: {
      name: string
      type: "S" | "N" | "B"
    }
    sortKey?: {
      name: string
      type: "S" | "N" | "B"
    }
    name: string
    status: string
    indexes: {
      partitionKey: {
        name: string
        type: "S" | "N" | "B"
      }
      sortKey?: {
        name: string
        type: "S" | "N" | "B"
      }
      name: string
      kind: "local" | "global"
      projection: {
        type: "ALL" | "KEYS_ONLY" | "INCLUDE"
        attributes?: string[]
      }
      status?: string
      backfilling?: boolean
      itemCount?: number
      sizeBytes?: number
    }[]
    itemCount: number
    sizeBytes: number
    billingMode: string
    tableClass: string
    deletionProtection: boolean
    createdAt?: number
  }
}
| {
  database: {
    type: "repository" | "database" | "bucket"
    name: string
    status?: "error" | "active" | "creating" | "deleting"
    createdAt?: number
    updatedAt?: number
    region: string
    orgId: string
    resourceId: string
    createdBy: string
    projectId?: string
    location: string
    arn?: string
    physicalName: string
  }
  table: null
}

Errors

Status	Message
`404`	Database not found
`404`	Table not found

Errors from AWS are mapped as in AWS errors.

`POST /v1/orgs/:orgId/databases/:resourceId/scan`

One page of a scan. Pass cursor from the previous page to continue.

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

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

Request body

Field	Type	Required	Default	Notes
`index`	`string`	No		up to 255 characters
`limit`	`integer`	No	`25`	1–100
`cursor`	`string`	No		up to 8,000 characters
`filters`	`object[]`	No	`[]`	up to 10 items
`filters[].attribute`	`string`	Yes		matches `^[^\u0000-\u001f]{1,255}$`
`filters[].op`	`"=" \| "<>" \| "<" \| "<=" \| ">" \| ">=" \| "begins_with" \| "contains" \| "between" \| "exists" \| "not_exists"`	Yes
`filters[].value`	`object \| object \| object \| object \| object`	No
`filters[].value2`	`object \| object \| object \| object \| object`	No
`match`	`"all" \| "any"`	No	`"all"`
`projection`	`string[]`	No		up to 50 items; each matches `^[^\u0000-\u001f]{1,255}$`

Response 200

{
  items: {
    [key: string]: {
      S?: string
      N?: string
      B?: string
      BOOL?: boolean
      NULL?: true
      M?: {
        [key: string]: {
          S?: string
          N?: string
          B?: string
          BOOL?: boolean
          NULL?: true
          M?: object
          L?: {
            S?: string
            N?: string
            B?: string
            BOOL?: boolean
            NULL?: true
            M?: object
            L?: object
            SS?: object
            NS?: object
            BS?: object
          }[]
          SS?: string[]
          NS?: string[]
          BS?: string[]
        }
      }
      L?: {
        S?: string
        N?: string
        B?: string
        BOOL?: boolean
        NULL?: true
        M?: {
          [key: string]: {
            S?: string
            N?: string
            B?: string
            BOOL?: boolean
            NULL?: true
            M?: object
            L?: object
            SS?: object
            NS?: object
            BS?: object
          }
        }
        L?: object
        SS?: string[]
        NS?: string[]
        BS?: string[]
      }[]
      SS?: string[]
      NS?: string[]
      BS?: string[]
    }
  }[]
  count: number
  scanned: number
  cursor?: string
  consumed?: number
}

Errors

Status	Message
`400`	No index named ….
`400`	A condition is missing its value.
`400`	Invalid page cursor. Run the request again.
`404`	Database not found
`404`	Table not found

Errors from AWS are mapped as in AWS errors.

`POST /v1/orgs/:orgId/databases/:resourceId/query`

One page of a query on the table or an index.

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

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

Request body

Field	Type	Required	Default	Notes
`index`	`string`	No		up to 255 characters
`limit`	`integer`	No	`25`	1–100
`cursor`	`string`	No		up to 8,000 characters
`filters`	`object[]`	No	`[]`	up to 10 items
`filters[].attribute`	`string`	Yes		matches `^[^\u0000-\u001f]{1,255}$`
`filters[].op`	`"=" \| "<>" \| "<" \| "<=" \| ">" \| ">=" \| "begins_with" \| "contains" \| "between" \| "exists" \| "not_exists"`	Yes
`filters[].value`	`object \| object \| object \| object \| object`	No
`filters[].value2`	`object \| object \| object \| object \| object`	No
`match`	`"all" \| "any"`	No	`"all"`
`projection`	`string[]`	No		up to 50 items; each matches `^[^\u0000-\u001f]{1,255}$`
`partition`	`object \| object \| object \| object \| object`	Yes
`sort`	`object`	No
`sort.op`	`"=" \| "<" \| "<=" \| ">" \| ">=" \| "begins_with" \| "between"`	Yes
`sort.value`	`object \| object \| object \| object \| object`	Yes
`sort.value2`	`object \| object \| object \| object \| object`	No
`forward`	`boolean`	No	`true`

Response 200

{
  items: {
    [key: string]: {
      S?: string
      N?: string
      B?: string
      BOOL?: boolean
      NULL?: true
      M?: {
        [key: string]: {
          S?: string
          N?: string
          B?: string
          BOOL?: boolean
          NULL?: true
          M?: object
          L?: {
            S?: string
            N?: string
            B?: string
            BOOL?: boolean
            NULL?: true
            M?: object
            L?: object
            SS?: object
            NS?: object
            BS?: object
          }[]
          SS?: string[]
          NS?: string[]
          BS?: string[]
        }
      }
      L?: {
        S?: string
        N?: string
        B?: string
        BOOL?: boolean
        NULL?: true
        M?: {
          [key: string]: {
            S?: string
            N?: string
            B?: string
            BOOL?: boolean
            NULL?: true
            M?: object
            L?: object
            SS?: object
            NS?: object
            BS?: object
          }
        }
        L?: object
        SS?: string[]
        NS?: string[]
        BS?: string[]
      }[]
      SS?: string[]
      NS?: string[]
      BS?: string[]
    }
  }[]
  count: number
  scanned: number
  cursor?: string
  consumed?: number
}

Errors

Status	Message
`400`	No index named ….
`400`	A condition is missing its value.
`400`	This table or index has no sort key.
`400`	The sort key condition is missing a value.
`400`	begins_with works on string and binary sort keys only.
`400`	Invalid page cursor. Run the request again.
`404`	Database not found
`404`	Table not found

Errors from AWS are mapped as in AWS errors.

`POST /v1/orgs/:orgId/databases/:resourceId/items/get`

Strongly consistent read of one item by key.

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

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

Request body

Field	Type	Required	Notes
`key`	`object`	Yes	values: any JSON

Response 200

{
  item: {
    [key: string]: {
      S?: string
      N?: string
      B?: string
      BOOL?: boolean
      NULL?: true
      M?: {
        [key: string]: {
          S?: string
          N?: string
          B?: string
          BOOL?: boolean
          NULL?: true
          M?: object
          L?: {
            S?: string
            N?: string
            B?: string
            BOOL?: boolean
            NULL?: true
            M?: object
            L?: object
            SS?: object
            NS?: object
            BS?: object
          }[]
          SS?: string[]
          NS?: string[]
          BS?: string[]
        }
      }
      L?: {
        S?: string
        N?: string
        B?: string
        BOOL?: boolean
        NULL?: true
        M?: {
          [key: string]: {
            S?: string
            N?: string
            B?: string
            BOOL?: boolean
            NULL?: true
            M?: object
            L?: object
            SS?: object
            NS?: object
            BS?: object
          }
        }
        L?: object
        SS?: string[]
        NS?: string[]
        BS?: string[]
      }[]
      SS?: string[]
      NS?: string[]
      BS?: string[]
    }
  }
}

Errors

Status	Message
`400`	A key has only ….
`404`	Database not found
`404`	Table not found
`404`	Item not found

Errors from AWS are mapped as in AWS errors.

`PUT /v1/orgs/:orgId/databases/:resourceId/items`

Writes an item. With originalKey, replaces that item (a key change moves it); with expected, the write fails with 409 if the item changed since it was read.

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

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

Request body (up to 800 KB)

Field	Type	Required	Notes
`item`	`object`	Yes	values: any JSON
`original`	`object`	No	values: any JSON

Errors

Status	Message
`400`	A key has only ….
`404`	Database not found
`404`	Table not found
`409`	An item with this key already exists.
`409`	This item was deleted. Create it again instead.
`413`	The item is larger than DynamoDB's 400 KB limit.

Errors from AWS are mapped as in AWS errors.

`POST /v1/orgs/:orgId/databases/:resourceId/items/delete`

Deletes items by key.

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
`key`	`object`	Yes	values: any JSON

Response 204 with no body.

Errors

Status	Message
`400`	A key has only ….
`404`	Database not found
`404`	Table not found

Errors from AWS are mapped as in AWS errors.

`POST /v1/orgs/:orgId/databases/:resourceId/indexes`

Adds a global secondary index. The table answers with status UPDATING while DynamoDB backfills the index.

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
`name`	`string`	Yes	matches `^[A-Za-z0-9_.-]{3,255}$`
`partitionKey`	`object`	Yes
`partitionKey.name`	`string`	Yes	matches `^[A-Za-z_][A-Za-z0-9_.-]{0,254}$`
`partitionKey.type`	`"S" \| "N" \| "B"`	Yes
`sortKey`	`object`	No
`sortKey.name`	`string`	Yes	matches `^[A-Za-z_][A-Za-z0-9_.-]{0,254}$`
`sortKey.type`	`"S" \| "N" \| "B"`	Yes
`projection`	`object`	Yes
`projection.type`	`"ALL" \| "KEYS_ONLY" \| "INCLUDE"`	Yes
`projection.attributes`	`string[]`	No	1–20 items; each matches `^[^\u0000-\u001f]{1,255}$`

Response 202

{
  table: {
    partitionKey: {
      name: string
      type: "S" | "N" | "B"
    }
    sortKey?: {
      name: string
      type: "S" | "N" | "B"
    }
    name: string
    status: string
    indexes: {
      partitionKey: {
        name: string
        type: "S" | "N" | "B"
      }
      sortKey?: {
        name: string
        type: "S" | "N" | "B"
      }
      name: string
      kind: "local" | "global"
      projection: {
        type: "ALL" | "KEYS_ONLY" | "INCLUDE"
        attributes?: string[]
      }
      status?: string
      backfilling?: boolean
      itemCount?: number
      sizeBytes?: number
    }[]
    itemCount: number
    sizeBytes: number
    billingMode: string
    tableClass: string
    deletionProtection: boolean
    createdAt?: number
  }
}

Errors

Status	Message
`400`	List the attributes to include.
`400`	The sort key must differ from the partition key.
`400`	… is already a … key attribute; use that type.
`404`	Database not found
`404`	Table not found
`409`	Indexes can only be added to on-demand tables here.
`409`	An index named … already exists.

Errors from AWS are mapped as in AWS errors.

`DELETE /v1/orgs/:orgId/databases/:resourceId/indexes/:indexName`

Removes a global secondary index.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:resourceId`	Resource id (`res_…`).
`:indexName`	Global secondary index name.

Response 202

{
  table: {
    partitionKey: {
      name: string
      type: "S" | "N" | "B"
    }
    sortKey?: {
      name: string
      type: "S" | "N" | "B"
    }
    name: string
    status: string
    indexes: {
      partitionKey: {
        name: string
        type: "S" | "N" | "B"
      }
      sortKey?: {
        name: string
        type: "S" | "N" | "B"
      }
      name: string
      kind: "local" | "global"
      projection: {
        type: "ALL" | "KEYS_ONLY" | "INCLUDE"
        attributes?: string[]
      }
      status?: string
      backfilling?: boolean
      itemCount?: number
      sizeBytes?: number
    }[]
    itemCount: number
    sizeBytes: number
    billingMode: string
    tableClass: string
    deletionProtection: boolean
    createdAt?: number
  }
}

Errors

Status	Message
`404`	Database not found
`404`	Table not found
`404`	Index not found
`409`	Local indexes can't be removed from a table.

Errors from AWS are mapped as in AWS errors.

`GET /v1/orgs/:orgId/databases/:resourceId/metrics`

Consumed capacity, throttles and latency from CloudWatch.

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
`range`	``	No	`"1h"`

Response 200

{
  range: "24h" | "7d" | "1h"
  period: 300 | 3600 | 60
  from: number
  to: number
  series: {
    t: number
    read: number
    write: number
    readThrottles: number
    writeThrottles: number
  }[]
  latency: {
    operations: string[]
    points: {
      [key: string]: null | number
      t: number
    }[]
  }
}

Errors

Status	Message
`404`	Database not found

Errors from AWS are mapped as in AWS errors.

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

Time to live, point-in-time recovery, deletion protection, table class and tags.

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

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

Response 200

{
  deletionProtection: boolean
  tableClass: string
  ttl: {
    status: "DISABLED" | "DISABLING" | "ENABLED" | "ENABLING"
    attribute?: string
  }
  pitr: {
    status: "DISABLED" | "ENABLED"
    recoveryPeriodDays?: number
    earliest?: number
    latest?: number
  }
  tags: {
    key: string
    value: string
  }[]
}

Errors

Status	Message
`404`	Database not found
`404`	Table not found

Errors from AWS are mapped as in AWS errors.

`PATCH /v1/orgs/:orgId/databases/:resourceId/settings`

Time to live, point-in-time recovery, deletion protection and table class.

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
`ttl`	`object`	No
`ttl.enabled`	`boolean`	Yes
`ttl.attribute`	`string`	No	matches `^[^\u0000-\u001f]{1,255}$`
`pitr`	`boolean`	No
`deletionProtection`	`boolean`	No
`tableClass`	`"STANDARD" \| "STANDARD_INFREQUENT_ACCESS"`	No

Also checked: Nothing to change.

Response 200

{
  deletionProtection: boolean
  tableClass: string
  ttl: {
    status: "DISABLED" | "DISABLING" | "ENABLED" | "ENABLING"
    attribute?: string
  }
  pitr: {
    status: "DISABLED" | "ENABLED"
    recoveryPeriodDays?: number
    earliest?: number
    latest?: number
  }
  tags: {
    key: string
    value: string
  }[]
}

Errors

Status	Message
`400`	Name the attribute that holds the expiry time.
`404`	Database not found
`404`	Table not found
`409`	Time to live isn't enabled.

Errors from AWS are mapped as in AWS errors.

`PATCH /v1/orgs/:orgId/databases/:resourceId/tags`

Adds, changes or removes the table's own tags. si: tags are the platform's and can't be changed.

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
`set`	`object`	No	`{}`	keys 1–128 characters, match `^[\p{L}\p{Z}\p{N}_.:/=+\-@]$`; values: string (up to 256 characters, matches `^[\p{L}\p{Z}\p{N}_.:/=+\-@]$`)
`remove`	`string[]`	No	`[]`	up to 50 items; each 1–128 characters, matches `^[\p{L}\p{Z}\p{N}_.:/=+\-@]*$`

Also checked: Nothing to change.

Response 200

{
  tags: {
    key: string
    value: string
  }[]
}

Errors

Status	Message
`404`	Database not found
`404`	Table not found

Errors from AWS are mapped as in AWS errors.

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

Deletes the table and its record. Refused while deletion protection is on.

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`	Database not found
`404`	Table not found
`409`	Turn off deletion protection first.
`409`	Wait for index … to finish …, then try again.

Errors from AWS are mapped as in AWS errors.

Databases

On this page