> ## Documentation Index
> Fetch the complete documentation index at: https://exsited.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# External databases

> Create external databases with tables and records, then list, read, search, insert and update their records.

External databases hold tables and records that you define through the API. You can create a database with its tables and first records, list and read databases and table columns, insert and update records, and search a table. This area has 7 endpoints, and all seven SDKs call every one.

> [!WARNING]
>
> **An external database cannot be deleted through the API.** Every database you create stays; to put its tables back to a known state, create it again with `replace` set to `true`.

## At a glance

| Endpoint | Method | Path | What it does |
| - | - | - | - |
| [List external databases](https://exsited.mintlify.site/api-reference/external-databases/list-external-databases.md) | GET | `/external_databases` | Returns the external databases on your instance, each with its `name`. |
| [Create an external database](https://exsited.mintlify.site/api-reference/external-databases/create-an-external-database.md) | POST | `/external_databases` | Creates a database with its tables and first records, and returns its name and a message. |
| [Retrieve an external database](https://exsited.mintlify.site/api-reference/external-databases/retrieve-an-external-database.md) | GET | `/external_databases/{db_name}` | Returns one external database by name, with its entries under `data`. |
| [Insert records into an external database table](https://exsited.mintlify.site/api-reference/external-databases/insert-records-into-an-external-database-table.md) | POST | `/external_databases/{db_name}/insert_records` | Adds rows to one table of a database and returns the inserted data. |
| [Search an external database table](https://exsited.mintlify.site/api-reference/external-databases/search-an-external-database-table.md) | POST | `/external_databases/{db_name}/search` | Returns the rows of one table of a database, with a count. |
| [Update records in an external database table](https://exsited.mintlify.site/api-reference/external-databases/update-records-in-an-external-database-table.md) | PATCH | `/external_databases/{db_name}/update_records` | Changes column values in the rows of a table that match a condition, and returns a message. |
| [Retrieve the columns of an external database table](https://exsited.mintlify.site/api-reference/external-databases/retrieve-the-columns-of-an-external-database-table.md) | GET | `/external_databases/{db_name}/tables/{table_name}` | Returns the columns of one table of a database, as a list under `data`. |

## Before you call

Register your API credentials once when your app starts, as shown in
[Authentication](https://exsited.mintlify.site/authentication.md). Every SDK sample on these pages then gets its client in one line.
With cURL, send the access token in an `Authorization` header: `Authorization: Bearer $ACCESS_TOKEN`.

## Things to know

* **Creating a database sends it under `external_database`.** The body has a `name` and a `tables` array; each table has `table_name`, `fields` and `records`.
* **Record writes and searches take the table at the top level.** Insert, update and search send `table_name` directly in the body with no wrapper key, and their responses come back under `external_database`.
* **Each record is a list of field and value pairs.** A record looks like `{"record": [{"field": "company", "value": "Acme Pty Ltd"}]}`.
* **Search results are grouped by table.** `list` holds one array per table name, each row maps column names to values, and `count` gives the number of rows.
* **Listings page with `has_next`, `has_prev` and `per_page`.** This differs from the cursor shape most other listings use; the entries are under `data`.
* **An unknown database name returns `404`.**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.