---
name: seren-db
description: "Create, manage, and query SerenDB databases through the first-class seren-db publisher."
---

# Seren DB

Use this skill when a user wants to create, manage, or query SerenDB serverless Postgres databases.

## API

Use this skill alongside the core Seren API skill (`https://api.serendb.com/skill.md`).

## Base Route

All routes go through `https://api.serendb.com/publishers/seren-db`.

## Authentication

All endpoints require `Authorization: Bearer $SEREN_API_KEY`.

## Projects

Manage SerenDB projects and fetch project-level connection URIs.

List all projects in the organization.

### GET `/publishers/seren-db/projects`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Create a new SerenDB project.

### POST `/publishers/seren-db/projects`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","region":""}'
```

Get a project by ID.

### GET `/publishers/seren-db/projects/{id}`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Delete a project.

### DELETE `/publishers/seren-db/projects/{id}`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-db/projects/<id>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Update a project.

### PATCH `/publishers/seren-db/projects/{id}`

```bash
curl -sS -X PATCH "https://api.serendb.com/publishers/seren-db/projects/<id>" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"block_public_connections":true,"block_vpc_connections":true,"compute_unit_max":0}'
```

Get connection URI for a project.

### GET `/publishers/seren-db/projects/{id}/connection_uri`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/connection_uri" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

## Branches

Create, inspect, rename, delete, set default branches, and manage branch expiration.

List all branches in a project.

### GET `/publishers/seren-db/projects/{id}/branches`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Create a new branch in a project.

### POST `/publishers/seren-db/projects/{id}/branches`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'
```

Get branch count for a project.

### GET `/publishers/seren-db/projects/{id}/branches/count`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/count" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Get a specific branch.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Delete a branch.

### DELETE `/publishers/seren-db/projects/{id}/branches/{bid}`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Rename a branch.

### PATCH `/publishers/seren-db/projects/{id}/branches/{bid}`

```bash
curl -sS -X PATCH "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'
```

Set a branch archived state.

### PATCH `/publishers/seren-db/projects/{id}/branches/{bid}/archived`

```bash
curl -sS -X PATCH "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/archived" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'
```

Get a branch connection string.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/connection-string`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/connection-string" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Get branch details.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/details`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/details" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Set branch expiration.

### PATCH `/publishers/seren-db/projects/{id}/branches/{bid}/expiration`

```bash
curl -sS -X PATCH "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/expiration" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_at":"2025-01-15T10:30:00Z"}'
```

Get LSN by timestamp for a branch.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/lsn_by_timestamp`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/lsn_by_timestamp?timestamp=<timestamp>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Get branch protection rule for a branch.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/protection`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/protection" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Create branch protection rule for a branch.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/protection`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/protection" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_bypass_roles":[""],"prevent_deletion":true,"prevent_reset":true}'
```

Delete branch protection rule for a branch.

### DELETE `/publishers/seren-db/projects/{id}/branches/{bid}/protection`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/protection" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Update branch protection rule for a branch.

### PATCH `/publishers/seren-db/projects/{id}/branches/{bid}/protection`

```bash
curl -sS -X PATCH "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/protection" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_bypass_roles":[""],"prevent_deletion":true,"prevent_reset":true}'
```

List publications for a branch.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/publications`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/publications" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Create a publication for a branch.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/publications`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/publications" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'
```

Delete a publication from a branch.

### DELETE `/publishers/seren-db/projects/{id}/branches/{bid}/publications/{publication_id}`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/publications/<publication_id>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Update a publication for a branch.

### PATCH `/publishers/seren-db/projects/{id}/branches/{bid}/publications/{publication_id}`

```bash
curl -sS -X PATCH "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/publications/<publication_id>" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"publish_delete":true,"publish_insert":true,"publish_truncate":true}'
```

List replication slots for a branch.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/replication-slots`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/replication-slots" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Create a replication slot for a branch.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/replication-slots`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/replication-slots" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'
```

Delete a replication slot from a branch.

### DELETE `/publishers/seren-db/projects/{id}/branches/{bid}/replication-slots/{slot_id}`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/replication-slots/<slot_id>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Reset a branch.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/reset`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/reset" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parent":true}'
```

Restore a branch.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/restore`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/restore" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preserve_under_name":"my-agent","source":null}'
```

Set a branch as the default for its project.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/set-default`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/set-default" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Set a branch as default using set_as_default alias.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/set_as_default`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/set_as_default" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Get timestamp by LSN for a branch.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/timestamp_by_lsn`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/timestamp_by_lsn?lsn=<lsn>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

## Databases

Manage databases within a specific branch.

List all databases on a branch.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/databases`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/databases" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Create a new database on a branch.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/databases`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/databases" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'
```

Get a specific database.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/databases/{did}`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/databases/<did>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Update a database (change owner).

### PUT `/publishers/seren-db/projects/{id}/branches/{bid}/databases/{did}`

```bash
curl -sS -X PUT "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/databases/<did>" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner_name":"my-agent"}'
```

Delete a database.

### DELETE `/publishers/seren-db/projects/{id}/branches/{bid}/databases/{did}`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/databases/<did>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

List all databases for a project.

### GET `/publishers/seren-db/projects/{id}/databases`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/databases" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

## Roles

Create, list, delete, reset, and reveal database role passwords.

List all roles on a branch.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/roles`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/roles" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Create a new role on a branch.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/roles`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/roles" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'
```

Delete a role from a branch.

### DELETE `/publishers/seren-db/projects/{id}/branches/{bid}/roles/{rid}`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/roles/<rid>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Reset a role's password.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/roles/{rid}/reset_password`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/roles/<rid>/reset_password" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Reveal a role password by role name.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/roles/{role_name}/reveal_password`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/roles/<role_name>/reveal_password" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

## Compute Endpoints

Manage branch compute endpoints, status checks, and restart lifecycle operations.

List all endpoints on a branch.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/endpoints`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/endpoints" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Create a new compute endpoint on a branch.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/endpoints`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/endpoints" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoscaling_max":0,"autoscaling_min":0,"compute_unit":""}'
```

Delete an endpoint.

### DELETE `/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/endpoints/<eid>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Update an endpoint's settings.

### PATCH `/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}`

```bash
curl -sS -X PATCH "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/endpoints/<eid>" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoscaling_max":0,"autoscaling_min":0,"compute_unit":""}'
```

Get endpoint health.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/health`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/endpoints/<eid>/health" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Get endpoint metrics.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/metrics`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/endpoints/<eid>/metrics" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Start a suspended endpoint.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/start`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/endpoints/<eid>/start" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Get endpoint status.

### GET `/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/status`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/endpoints/<eid>/status" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Stop (suspend) an endpoint.

### POST `/publishers/seren-db/projects/{id}/branches/{bid}/endpoints/{eid}/stop`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/branches/<bid>/endpoints/<eid>/stop" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

List all endpoints for a project.

### GET `/publishers/seren-db/projects/{id}/endpoints`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-db/projects/<id>/endpoints" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Delete a project endpoint.

### DELETE `/publishers/seren-db/projects/{id}/endpoints/{eid}`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-db/projects/<id>/endpoints/<eid>" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Update a project endpoint.

### PATCH `/publishers/seren-db/projects/{id}/endpoints/{eid}`

```bash
curl -sS -X PATCH "https://api.serendb.com/publishers/seren-db/projects/<id>/endpoints/<eid>" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoscaling_max":0,"autoscaling_min":0,"compute_unit":""}'
```

Restart an endpoint by project and endpoint ID.

### POST `/publishers/seren-db/projects/{id}/endpoints/{eid}/restart`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/endpoints/<eid>/restart" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Start a project endpoint.

### POST `/publishers/seren-db/projects/{id}/endpoints/{eid}/start`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/endpoints/<eid>/start" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Suspend a project endpoint.

### POST `/publishers/seren-db/projects/{id}/endpoints/{eid}/suspend`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/projects/<id>/endpoints/<eid>/suspend" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

## SQL Query

Execute SQL against a target project/branch/database using SerenDB credentials.

Execute a SQL query against a SerenDB database.

### POST `/publishers/seren-db/query`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-db/query" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT 1"}'
```