# Databases (/en/docs/api/native/database/databases)



[Guide →](/en/docs/developers/services/database/quickstart)

[Base URL and authentication](/en/docs/api/native/database)

## Create database [#create-database]

`POST /database/v1/databases`

### Request body [#request-body]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| name | string | yes | Display name for the database: 1–64 visible characters after trimming; control characters are rejected. It is not an identifier, so later calls still use the returned id. |
| labels | object | no | Optional string tags to attach, at most 64. Each key starts with a lowercase letter and may use up to 63 characters of a-z 0-9 _ -; each value is up to 63 characters of a-z 0-9 _ -. List calls filter on exact key and value pairs. |

Returns: `Database`.

### Response [#response]

#### HTTP 201 [#http-201]

Success

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| name | string | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |

```bash
curl -X POST "https://api.deepraxis.ai/database/v1/databases" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"walk-lib-r1-DOC-5320-tasks","labels":{"purpose":"docs","sample":"walk-lib-r1-doc-5320-"}}'
```

Response example — HTTP 201

```json
{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-tasks",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:41.488Z",
  "deleted_at": null,
  "purge_at": null
}
```

## List databases [#list-databases]

`GET /database/v1/databases`

| Parameter | Location | Description |
| --- | --- | --- |
| cursor | query | Opaque next_cursor from the previous page. |
| limit | query | Page size. (default: 20) (1–100) |
| labels | query | Exact label match, encoded as labels[purpose]=docs. |
| status | query | Filter by lifecycle state. active (the default when omitted) lists usable databases; deleting lists databases that were deleted and are still inside the seven-day restore window. Any other value returns 400 INVALID_PARAMS. |

Returns: `Page + object`.

### Response [#response-1]

#### HTTP 200 [#http-200]

Success

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| data | array<object> | Databases on this page, newest first (created_at descending, ties by id). Deleting databases are excluded unless status=deleting. |
| data[].id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| data[].name | string | Display name given at creation or by the last update; it is not an identifier. |
| data[].labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| data[].status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| data[].table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| data[].size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| data[].created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| data[].updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| data[].deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| data[].purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |
| next_cursor | string | null | Opaque cursor for the next page, or null when there are no more items. Databases list: pass it as cursor. Events list: pass it as after_seq (order asc) or before_seq (order desc). |

```bash
curl -g -X GET "https://api.deepraxis.ai/database/v1/databases?limit=10&labels[purpose]=docs&labels[sample]=walk-lib-r1-doc-5320-" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

Response example — HTTP 200

```json
{
  "data": [
    {
      "id": "db_d6f0d743d5a645e8",
      "name": "walk-lib-r1-DOC-5320-tasks",
      "labels": {
        "purpose": "docs",
        "sample": "walk-lib-r1-doc-5320-"
      },
      "status": "active",
      "table_count": 0,
      "size_bytes": 53248,
      "created_at": "2026-10-11T17:41:40.620Z",
      "updated_at": "2026-10-11T17:41:41.488Z",
      "deleted_at": null,
      "purge_at": null
    }
  ],
  "next_cursor": null
}
```

## Get database [#get-database]

`GET /database/v1/databases/{database_id}`

| Parameter | Location | Description |
| --- | --- | --- |
| database_id | path | Identifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted. |

Returns: `Database`.

### Response [#response-2]

#### HTTP 200 [#http-200-1]

Success

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| name | string | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |

```bash
curl -X GET "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

Response example — HTTP 200

```json
{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-tasks",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:41.488Z",
  "deleted_at": null,
  "purge_at": null
}
```

## Update database [#update-database]

`PATCH /database/v1/databases/{database_id}`

| Parameter | Location | Description |
| --- | --- | --- |
| database_id | path | Identifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted. |

### Request body [#request-body-1]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| name | string | no | New display name, 1–64 visible characters after trimming. Omit it to keep the current name. |
| labels | object | no | Complete replacement label set, not a merge: labels not listed here are removed. Same limits as at creation (at most 64; keys a-z 0-9 _ - starting with a letter; values up to 63 characters of a-z 0-9 _ -). Omit it to keep the current labels. |

Returns: `Database`.

### Response [#response-3]

#### HTTP 200 [#http-200-2]

Success

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| name | string | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |

```bash
curl -X PATCH "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"walk-lib-r1-DOC-5320-notes"}'
```

Response example — HTTP 200

```json
{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-notes",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:43.514Z",
  "deleted_at": null,
  "purge_at": null
}
```

## Delete database [#delete-database]

`DELETE /database/v1/databases/{database_id}`

| Parameter | Location | Description |
| --- | --- | --- |
| database_id | path | Identifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted. |

Returns: `Database`.

### Response [#response-4]

#### HTTP 200 [#http-200-3]

Success

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| name | string | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |

```bash
curl -X DELETE "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

Response example — HTTP 200

```json
{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-notes",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "deleting",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:51.868Z",
  "deleted_at": "2026-10-11T17:41:51.868Z",
  "purge_at": "2026-10-18T17:41:51.868Z"
}
```

## Restore database [#restore-database]

`POST /database/v1/databases/{database_id}/restore`

| Parameter | Location | Description |
| --- | --- | --- |
| database_id | path | Identifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted. |

Returns: `Database`.

### Response [#response-5]

#### HTTP 200 [#http-200-4]

Success

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| id | string | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path. |
| name | string | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | String tags attached to the database, as key and value pairs; empty object when none. |
| status | string | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | string | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | string | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | string | null | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | string | null | Permanent deletion deadline for deleting databases; null otherwise. |

```bash
curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/restore" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

Response example — HTTP 200

```json
{
  "id": "db_d6f0d743d5a645e8",
  "name": "walk-lib-r1-DOC-5320-notes",
  "labels": {
    "purpose": "docs",
    "sample": "walk-lib-r1-doc-5320-"
  },
  "status": "active",
  "table_count": 0,
  "size_bytes": 53248,
  "created_at": "2026-10-11T17:41:40.620Z",
  "updated_at": "2026-10-11T17:41:51.528Z",
  "deleted_at": null,
  "purge_at": null
}
```

## Purge database [#purge-database]

`POST /database/v1/databases/{database_id}/purge`

| Parameter | Location | Description |
| --- | --- | --- |
| database_id | path | Identifier of the database to act on: the id (db_…) returned by databaseCreateDatabase or databaseListDatabases. A display name is not accepted. |

Returns: `object`.

### Response [#response-6]

#### HTTP 200 [#http-200-5]

Permanently purged

**application/json**

| Name | Type | Description |
| --- | --- | --- |
| id | string | Id (db_…) of the database that was permanently purged; it no longer resolves. |
| object | string | Resource type of the purged object; always database. |
| purged | boolean | Always true: the database and all of its data were permanently removed and cannot be recovered. |

```bash
curl -X POST "https://api.deepraxis.ai/database/v1/databases/${DATABASE_ID}/purge" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

Response example — HTTP 200

```json
{
  "id": "db_d6f0d743d5a645e8",
  "object": "database",
  "purged": true
}
```

## Database [#database]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | yes | Database identifier, prefixed db_. Pass it as database_id in every database, table, field, rows and events path.; ^db_ |
| name | string | yes | Display name given at creation or by the last update; it is not an identifier. |
| labels | object | yes | String tags attached to the database, as key and value pairs; empty object when none. |
| status | "provisioning" / "active" / "deleting" / "deleted" / "failed" | yes | Lifecycle state of the database. Table, field and row calls work only while it is active. |
| table_count | integer | yes | Number of tables currently in the database, at most 50; refreshed when the schema changes. |
| size_bytes | integer | yes | Storage size; row writes and GET refresh usage at most once per five seconds, schema changes refresh immediately. |
| created_at | date-time | yes | Time the database was created, as an RFC 3339 UTC timestamp. |
| updated_at | date-time | yes | Time of the last change to the name, labels, status or usage snapshot, as an RFC 3339 UTC timestamp. |
| deleted_at | date-time / null | yes | Time the database entered the deleting state, as an RFC 3339 UTC timestamp; null while it is active and again after a restore. |
| purge_at | date-time / null | yes | Permanent deletion deadline for deleting databases; null otherwise. |

## Page [#page]

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| data | JSON[] | yes | Items of this page; the item type depends on the operation. |
| next_cursor | string / null | yes | Opaque cursor for the next page, or null when there are no more items. Databases list: pass it as cursor. Events list: pass it as after_seq (order asc) or before_seq (order desc). |