Databases overview
The Databases API lets your applications work with the PostgreSQL databases in an Intellectible project. Create tables, read and update data, execute SQL, or import CSV files from the project Library. These are the same project databases available in the app, workflows, and the agent.
For working with databases in the app, see the Databases guide.
Before you start
Follow the API quickstart to get your project ID and API key. Examples in this section use:
export INTELLECTIBLE_PUBLIC_API_URL="https://app.intellectible.com/api/publicv1"
export INTELLECTIBLE_PROJECT_ID="your_project_id"
export INTELLECTIBLE_DATABASE_ID="your_database_id"
export INTELLECTIBLE_TABLE_ID="customers"
Set INTELLECTIBLE_PROJECT_API_KEY using the hidden-input prompt in the quickstart, so the key does not appear in your shell history. Send it in the Authorization header without a Bearer prefix. Keep keys in server-side code and out of source control.
Use List databases to find a database ID, and List tables to find table names. A database’s display name is not its ID.
Permissions
Database grants can be scoped to a particular database ID. Listing all databases and creating a new database require a grant on all.
| Permission | Operations |
|---|---|
databases.read | List databases/tables, inspect table schemas, read rows, and check CSV import status. |
databases.write | Insert or update rows, update a cell, and start CSV imports. Inserts and imports can also add missing columns. |
databases.delete | Delete rows by ID. |
databases.schema | Create or delete tables and columns. |
databases.query | Execute SQL, including SQL that changes data or schema. |
databases.admin | Create or delete whole databases. |
library.read | Read CSV headers and read the Library file for an import. |
These are independent actions, not a hierarchy: a write grant does not automatically grant read, and a read grant does not permit SQL. query is powerful because SQL can perform destructive operations. CSV imports require both the database write and Library read grants.
See Authentication and permissions for key configuration.
Table and column names
The structured endpoints accept names containing lowercase letters and digits, separated by single underscores, with a maximum length of 63 characters. Examples: customers, order_items, signup_date.
Do not use spaces, uppercase letters, leading or trailing underscores, or consecutive underscores. Database IDs and Library file IDs are generated identifiers, not table names, so this naming rule does not apply to them.
Working with data
A typical integration:
- Create a database or select an existing one.
- Create a table and optionally define its columns.
- Insert rows or import a Library CSV.
- Read pages of rows and update individual values.
Read rows supports column selection, sorting, and offset pagination, with a maximum of 1000 rows per request. Use Run SQL for filters, joins, aggregation, and more advanced operations.
Inserts can add columns and update existing records when unique values match. CSV imports instead append data in the background. Read the individual endpoint guidance before treating either operation as a simple append or a safe retry.
Errors and safe retries
Validation errors usually return 400, invalid credentials 401, insufficient permissions or quota failures 403, and missing resources 404. Requests can also be rate-limited with 429. Database execution, constraint, and some validation failures can return 500, so inspect the response rather than assuming every 500 is safe to retry.
A database error commonly includes error and message. Authentication errors can be plain text. See Errors, limits and retries for shared handling.
A timeout or failure does not guarantee that no data changed. Large inserts and CSV imports can commit in batches. Check the stored data or import status before retrying a write. Deleting databases, tables, columns, or rows is destructive; these endpoints do not provide an undo operation.
Endpoints
Databases and schema
- List databases
- Create a database
- Delete a database
- List tables
- Create a table
- Get a table’s schema
- Delete a table
- Create a column
- Delete a column