Tables and columns

Which tables the agent may query, and the descriptions it reads them by.

Base URL https://futuresmart.ai/database-agent/api · every request sends X-API-Key. Samples read the key from DATABASE_AGENT_API_KEY. All endpoints

Db List Tables

GET/v1/agents/{agent_id}/databases/{db_id}/tables

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.get(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables`, {
  method: "GET",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X GET "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

Db Create Tables

POST/v1/agents/{agent_id}/databases/{db_id}/tables

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`

Request body · multipart/form-data (optional)

Name	Type	Description
`file`	`string \| null`
`table_descriptions`	`string \| null`

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.post(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables",
    headers={"X-API-Key": API_KEY},
    data={"file": "<file>", "table_descriptions": "<table_descriptions>"},
    timeout=120,
)
r.raise_for_status()
print(r.json())

import { readFile } from "node:fs/promises";

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const form = new FormData();
form.append("file", "<file>");
form.append("table_descriptions", "<table_descriptions>");

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables`, {
  method: "POST",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
  body: form,
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X POST "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY" \
  -F "file=<file>" \
  -F "table_descriptions=<table_descriptions>"

Db Put Tables

PUT/v1/agents/{agent_id}/databases/{db_id}/tables

Bulk update table descriptions for a db_id — merges into the existing set (does not blank tables absent from the payload). Accepts a bare [{table_name, description}] array, a {"tables": [...]} object, or a file. Returns an "updated" message.

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`

Request body · multipart/form-data (optional)

Name	Type	Description
`file`	`string \| null`
`table_descriptions`	`string \| null`

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.put(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables",
    headers={"X-API-Key": API_KEY},
    data={"file": "<file>", "table_descriptions": "<table_descriptions>"},
    timeout=120,
)
r.raise_for_status()
print(r.json())

import { readFile } from "node:fs/promises";

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const form = new FormData();
form.append("file", "<file>");
form.append("table_descriptions", "<table_descriptions>");

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables`, {
  method: "PUT",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
  body: form,
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X PUT "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY" \
  -F "file=<file>" \
  -F "table_descriptions=<table_descriptions>"

Db Delete Tables

DELETE/v1/agents/{agent_id}/databases/{db_id}/tables

Clear table descriptions. Body: {"table_names": ["t1","t2"]} for some, or {"delete_all": true} for all. (Tables are not deleted — only their description text is cleared.)

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`

Request body · application/json

Name	Type	Description
`table_names`	`array<string> \| null`	Table names to clear
`delete_all`	`boolean`	Clear ALL table descriptions for this databaseDefault: false

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.delete(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables",
    headers={"X-API-Key": API_KEY},
    json={
        "delete_all": False,
    },
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables`, {
  method: "DELETE",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "delete_all": false
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X DELETE "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delete_all": false
  }'

Example request body

JSON

{
  "delete_all": false
}

Db Generate Table Descriptions

POST/v1/agents/{agent_id}/databases/{db_id}/tables/generate

Start an async job that auto-generates a description for every table in the DB (via LLM). overwrite=true regenerates all tables; default only fills tables whose description is currently blank (manually-set ones are preserved). Poll the returned job_id.

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`

Query parameters

Name	Type	Description
`overwrite`	`boolean`	true = regenerate ALL tables; false (default) = only fill tables whose description is blank (manual ones preserved)Default: false

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.post(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/generate",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/generate`, {
  method: "POST",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X POST "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/generate" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

Db Poll Table Descriptions

GET/v1/agents/{agent_id}/databases/{db_id}/tables/generate/{job_id}

Poll a table-description generation job → {status, message, error}.

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`
`job_id`required	`string`

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.get(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/generate/YOUR_JOB_ID",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/generate/YOUR_JOB_ID`, {
  method: "GET",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X GET "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/generate/YOUR_JOB_ID" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

Db Generate One Table Description

POST/v1/agents/{agent_id}/databases/{db_id}/tables/{table_name}/generate

Auto-generate (LLM) + save the description for a SINGLE table. Synchronous — returns {table_name, description} directly (no job/poll). Other tables and flags are untouched.

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`
`table_name`required	`string`

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.post(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/generate",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/generate`, {
  method: "POST",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X POST "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/generate" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

Db Table Visibility

PATCH/v1/agents/{agent_id}/databases/{db_id}/tables/{table_name}/visibility

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`
`table_name`required	`string`

Request body · application/json (optional)

Name	Type	Description
`is_included`required	`boolean`	Whether table is included

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.patch(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/visibility",
    headers={"X-API-Key": API_KEY},
    json={
        "is_included": False,
    },
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/visibility`, {
  method: "PATCH",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "is_included": false
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X PATCH "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/visibility" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_included": false
  }'

Example request body

JSON

{
  "is_included": false
}

Db Update Table Description

PUT/v1/agents/{agent_id}/databases/{db_id}/tables/{table_name}

Update the description for a single table in the given db_id.

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`
`table_name`required	`string`

Request body · application/json (optional)

Name	Type	Description
`description`required	`string`	Table description
`is_included`	`boolean \| null`	Whether table is included (optional)

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.put(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME",
    headers={"X-API-Key": API_KEY},
    json={
        "description": "<description>",
    },
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME`, {
  method: "PUT",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "description": "<description>"
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X PUT "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "<description>"
  }'

Example request body

JSON

{
  "description": "<description>"
}

Db Get Columns

GET/v1/agents/{agent_id}/databases/{db_id}/tables/{table_name}/columns

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`
`table_name`required	`string`

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.get(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/columns",
    headers={"X-API-Key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/columns`, {
  method: "GET",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X GET "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/columns" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY"

Db Update Columns

PUT/v1/agents/{agent_id}/databases/{db_id}/tables/{table_name}/columns

Credential Database Agent API key for this agent (X-API-Key)

Path parameters

Name	Type	Description
`agent_id`required	`string`
`db_id`required	`string`
`table_name`required	`string`

Request body · application/json (optional)

Name	Type	Description
`user_id`	`string \| null`	User ID (optional if using auth token)
`columns`required	`array<ColumnDescriptionUpdate>`	List of column descriptions
`↳ column_name`required	`string`	Name of the column
`↳ description`required	`string`	Description of the column

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/database-agent/api"
API_KEY = os.environ["DATABASE_AGENT_API_KEY"]

r = requests.put(
    f"{API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/columns",
    headers={"X-API-Key": API_KEY},
    json={
        "columns": [{
            "column_name": "<column_name>",
            "description": "<description>",
        }],
    },
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/database-agent/api";

const res = await fetch(`${API_ROOT}/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/columns`, {
  method: "PUT",
  headers: { "X-API-Key": process.env.DATABASE_AGENT_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "columns": [
      {
        "column_name": "<column_name>",
        "description": "<description>"
      }
    ]
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X PUT "https://futuresmart.ai/database-agent/api/v1/agents/YOUR_AGENT_ID/databases/YOUR_DB_ID/tables/YOUR_TABLE_NAME/columns" \
  -H "X-API-Key: $DATABASE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": [
      {
        "column_name": "<column_name>",
        "description": "<description>"
      }
    ]
  }'

Example request body

JSON

{
  "columns": [
    {
      "column_name": "<column_name>",
      "description": "<description>"
    }
  ]
}