Skip to content

Databases (extracted tables) ​

The Databases tab of Apps: tables whose rows are extracted from documents by the data-extractor service (one row per source document), grouped into table databases. Requests are proxied to the extractor service; the API adds authentication and ownership checks.

Endpoints ​

MethodPathPurpose
GET/microservices/data-extractor/tablesList my tables
GET/microservices/data-extractor/tableFetch several tables
POST/microservices/data-extractor/create_tableCreate a table
PUT/microservices/data-extractor/update_table/{table_id}Update a table's schema
GET/microservices/data-extractor/table/{table_id}Get a table
DELETE/microservices/data-extractor/table/{table_id}Delete a table
PATCH/microservices/data-extractor/table/{table_id}/rows/{source_uid}Edit cells of one row
DELETE/microservices/data-extractor/table/{table_id}/rows/{source_uid}Delete a row
GET/microservices/data-extractor/table/{table_id}/exportExport a table to Excel
GET/microservices/data-extractor/table/{table_id}/highlightsEvidence highlights for extracted values
POST/microservices/data-extractor/chatChat with a table (extractor service)
POST/microservices/agent/table-chat/Ask the assistant about a table
GET/microservices/data-extractor/tables_databaseList my table databases
POST/microservices/data-extractor/tables_databaseCreate a table database
GET/microservices/data-extractor/tables_database/{db_id}Get a table database
PUT/microservices/data-extractor/tables_database/{db_id}Rename or re-order a table database
DELETE/microservices/data-extractor/tables_database/{db_id}Delete a table database

GET /microservices/data-extractor/tables ​

List my tables

Tables owned by the caller (scoped by the account's email). No trailing slash on this path.

Auth: Session token · In the app: Apps → Databases; Table builder gallery

Query parameters

FieldTypeRequiredDescription
organization_namestringno

Response 200 — Tables (service response).

FieldTypeDescription
countintegerNumber of tables returned.
tablesobject[]
tables[].table_idstring
tables[].table_namestring
tables[].emailstringOwner (account email).
tables[].organization_namestring
tables[].columnsobject[]
tables[].columns[].namestringColumn key (also the key of each row's data). Metacharacters are stripped.
tables[].columns[].instructionstringWhat the extractor should pull from each document into this column.
tables[].columns[].output_typestring ("string", "number", "list", "boolean", "object", "reference")Default: "string".
tables[].rowsobject[]
tables[].rows[].source_uidstringIdentity of the source (document uid or text input). Rows sharing a uid are addressed together.
tables[].rows[].dataobjectCell values keyed by column name.
tables[].rows[].filenamestring
tables[].rows[].created_atstring (date-time)
tables[].rows[].updated_atstring (date-time)
tables[].rows[].processed_atstring (date-time), nullable
tables[].metadataobjectFree-form (e.g. column_widths).
tables[].created_atstring (date-time)
tables[].updated_atstring (date-time)

Response 403 — The account has no email address.

Response 503 — Extractor service not configured.

Example

bash
curl -X GET "https://api.example.com/microservices/data-extractor/tables" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/data-extractor/table ​

Fetch several tables

Auth: Session token

Query parameters

FieldTypeRequiredDescription
idsstringyesComma-separated table ids. All must be yours or shared with you.

Response 200 — Tables.

FieldTypeDescription
countinteger
tablesobject[]
tables[].table_idstring
tables[].table_namestring
tables[].emailstringOwner (account email).
tables[].organization_namestring
tables[].columnsobject[]
tables[].columns[].namestringColumn key (also the key of each row's data). Metacharacters are stripped.
tables[].columns[].instructionstringWhat the extractor should pull from each document into this column.
tables[].columns[].output_typestring ("string", "number", "list", "boolean", "object", "reference")Default: "string".
tables[].rowsobject[]
tables[].rows[].source_uidstringIdentity of the source (document uid or text input). Rows sharing a uid are addressed together.
tables[].rows[].dataobjectCell values keyed by column name.
tables[].rows[].filenamestring
tables[].rows[].created_atstring (date-time)
tables[].rows[].updated_atstring (date-time)
tables[].rows[].processed_atstring (date-time), nullable
tables[].metadataobjectFree-form (e.g. column_widths).
tables[].created_atstring (date-time)
tables[].updated_atstring (date-time)

Response 400 — ids missing.

Response 403 — One of the tables is not accessible.

Example

bash
curl -X GET "https://api.example.com/microservices/data-extractor/table?ids=tbl_9f8e7d6c%2Ctbl_1a2b3c4d" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/data-extractor/create_table ​

Create a table

Defines the schema (and optionally seed rows). The owner and organisation are taken from the session. Column names are sanitised.

Auth: Session token · In the app: Table builder → Save table (new)

Request body (application/json)

FieldTypeRequiredDescription
table_namestringyes
columnsobject[]yes
columns[].namestringyesColumn key (also the key of each row's data). Metacharacters are stripped.
columns[].instructionstringnoWhat the extractor should pull from each document into this column.
columns[].output_typestring ("string", "number", "list", "boolean", "object", "reference")noDefault: "string".
rowsobject[]no
rows[].source_uidstringnoIdentity of the source (document uid or text input). Rows sharing a uid are addressed together.
rows[].dataobjectnoCell values keyed by column name.
rows[].filenamestringno
rows[].created_atstring (date-time)no
rows[].updated_atstring (date-time)no
rows[].processed_atstring (date-time), nullableno
metadataobjectno
workflow_idstringnoRecords which workflow created the table (for cascade deletes).
json
{
  "table_name": "Supplier invoices",
  "columns": [
    {
      "name": "supplier",
      "instruction": "The supplier's legal name.",
      "output_type": "string"
    },
    {
      "name": "invoice_total",
      "instruction": "Total payable as a number.",
      "output_type": "number"
    }
  ]
}

Response 200 — Created (service response; includes table_id).

FieldTypeDescription
table_idstring

Response 502 — Extractor service error.

Example

bash
curl -X POST "https://api.example.com/microservices/data-extractor/create_table" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"table_name":"Supplier invoices","columns":[{"name":"supplier","instruction":"The supplier's legal name.","output_type":"string"},{"name":"invoice_total","instruction":"Total payable as a number.","output_type":"number"}]}'

PUT /microservices/data-extractor/update_table/{table_id} ​

Update a table's schema

Partial update of table_name, columns (full array replaces the schema) and metadata (merged). rows are ignored unless the body also carries replace_rows: true, in which case the array replaces every stored row ([] clears the table). Use the row endpoints for single-cell edits and row deletes. Requires write access (owner or editor grant).

Auth: Session token · In the app: Table builder → Save table; column resize

Path parameters

FieldTypeRequiredDescription
table_idstringyes

Request body (application/json)

FieldTypeRequiredDescription
table_namestringno
columnsobject[]no
columns[].namestringyesColumn key (also the key of each row's data). Metacharacters are stripped.
columns[].instructionstringnoWhat the extractor should pull from each document into this column.
columns[].output_typestring ("string", "number", "list", "boolean", "object", "reference")noDefault: "string".
metadataobjectno
rowsobject[]no
rows[].source_uidstringnoIdentity of the source (document uid or text input). Rows sharing a uid are addressed together.
rows[].dataobjectnoCell values keyed by column name.
rows[].filenamestringno
rows[].created_atstring (date-time)no
rows[].updated_atstring (date-time)no
rows[].processed_atstring (date-time), nullableno
replace_rowsbooleannoDefault: false.

Response 200 — Result.

FieldTypeDescription
table_idstring
existing_rowsinteger
columns_addedstring[]
columns_removedstring[]
warningstring

Response 403 — Read-only or no access.

Example

bash
curl -X PUT "https://api.example.com/microservices/data-extractor/update_table/tbl_9f8e7d6c" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/data-extractor/table/{table_id} ​

Get a table

Auth: Session token · In the app: Apps → Databases → open table

Path parameters

FieldTypeRequiredDescription
table_idstringyes

Response 200 — The table with its rows.

FieldTypeDescription
table_idstring
table_namestring
emailstringOwner (account email).
organization_namestring
columnsobject[]
columns[].namestringColumn key (also the key of each row's data). Metacharacters are stripped.
columns[].instructionstringWhat the extractor should pull from each document into this column.
columns[].output_typestring ("string", "number", "list", "boolean", "object", "reference")Default: "string".
rowsobject[]
rows[].source_uidstringIdentity of the source (document uid or text input). Rows sharing a uid are addressed together.
rows[].dataobjectCell values keyed by column name.
rows[].filenamestring
rows[].created_atstring (date-time)
rows[].updated_atstring (date-time)
rows[].processed_atstring (date-time), nullable
metadataobjectFree-form (e.g. column_widths).
created_atstring (date-time)
updated_atstring (date-time)
json
{
  "table_id": "tbl_9f8e7d6c",
  "table_name": "Supplier invoices",
  "email": "jane@acme.com",
  "organization_name": "Acme",
  "columns": [
    {
      "name": "supplier",
      "instruction": "The supplier's legal name.",
      "output_type": "string"
    },
    {
      "name": "invoice_total",
      "instruction": "Total payable as a number.",
      "output_type": "number"
    }
  ],
  "rows": [
    {
      "source_uid": "1b6c1c1e-9d0a-4b6e-9f2a-3c4d5e6f7a8b",
      "filename": "invoice-1042.pdf",
      "data": {
        "supplier": "Globex",
        "invoice_total": 1250.5
      }
    }
  ],
  "metadata": {
    "column_widths": {
      "supplier": 220
    }
  },
  "created_at": "2026-09-01T09:00:00Z",
  "updated_at": "2026-09-22T08:05:41Z"
}

Response 403 — Not yours / not shared with you.

Response 404 — Unknown table.

Example

bash
curl -X GET "https://api.example.com/microservices/data-extractor/table/tbl_9f8e7d6c" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /microservices/data-extractor/table/{table_id} ​

Delete a table

Owner only.

Auth: Session token

Path parameters

FieldTypeRequiredDescription
table_idstringyes

Response 200 — Deleted (service response).

Example

bash
curl -X DELETE "https://api.example.com/microservices/data-extractor/table/<table_id>" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PATCH /microservices/data-extractor/table/{table_id}/rows/{source_uid} ​

Edit cells of one row

Values are coerced to the column's output_type; machine-managed columns (processed_at, created_at, updated_at, filename) are refused; the edited cell's evidence highlight is dropped. All rows sharing the source_uid are affected.

Auth: Session token · In the app: Table cell edit; evidence viewer field edit

Path parameters

FieldTypeRequiredDescription
table_idstringyes
source_uidstringyes

Request body (application/json)

FieldTypeRequiredDescription
dataobjectyesColumn → new value.
json
{
  "data": {
    "invoice_total": 1260
  }
}

Response 200 — Updated row (service response).

Response 403 — No write access.

Example

bash
curl -X PATCH "https://api.example.com/microservices/data-extractor/table/<table_id>/rows/<source_uid>" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"invoice_total":1260}}'

DELETE /microservices/data-extractor/table/{table_id}/rows/{source_uid} ​

Delete a row

Auth: Session token

Path parameters

FieldTypeRequiredDescription
table_idstringyes
source_uidstringyes

Response 200 — Deleted (service response).

Example

bash
curl -X DELETE "https://api.example.com/microservices/data-extractor/table/<table_id>/rows/<source_uid>" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/data-extractor/table/{table_id}/export ​

Export a table to Excel

Writes the table to an .xlsx in your media storage and returns where it is — not the file itself. Download it from saved_path with a signed URL, as the app does.

Citation links. Reference cells link to the source PDFs. Inside the app those links are signed as you click them; in an exported file they would expire within the hour. With permanent_links=1 every such link is rewritten into a permanent link so it keeps opening after the file is shared.

Permanent links are public: anyone holding the file can open the linked PDFs without signing in, including people outside your organisation if it is forwarded. Only files you own are linked (refused counts the rest); links are reused across re-exports of the same table and stay revocable from My Data → Artifacts → Links, and die with the file. Signing is best effort — the export succeeds even when some links cannot be made.

Auth: Session token · In the app: Apps → Databases → Export to Excel

Path parameters

FieldTypeRequiredDescription
table_idstringyes

Query parameters

FieldTypeRequiredDescription
permanent_linksbooleannoRewrite citation links into permanent public links. Accepts 1, true or yes. Default: false.

Response 200 — Exported.

FieldTypeDescription
saved_pathstringMedia path of the workbook.
filenamestring
permanent_linksobjectPresent only when permanent_links was requested.
permanent_links.cellsintegerCells that contained a citation link.
permanent_links.signedintegerLinks rewritten to permanent links.
permanent_links.refusedintegerLinks left as they were — typically files you don't own.
json
{
  "saved_path": "Acme/pdf_extracted/jane/invoices_2026-09-25.xlsx",
  "filename": "invoices_2026-09-25.xlsx",
  "permanent_links": {
    "cells": 214,
    "signed": 212,
    "refused": 2
  }
}

Response 404 — Not your table.

Response 503 — Extractor service not configured.

Example

bash
curl "https://api.example.com/microservices/data-extractor/table/tbl_9f8e7d6c/export?permanent_links=1"           -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/data-extractor/table/{table_id}/highlights ​

Evidence highlights for extracted values

Where in the source document each value came from: per field, the verbatim quote and rectangles to draw over the rendered PDF (rect is [x0, y0, x1, y1] as fractions of the page from the top-left; page is 1-based). Empty lists are normal (older extractions, text inputs, non-PDF sources).

Auth: Session token · In the app: Evidence viewer

Path parameters

FieldTypeRequiredDescription
table_idstringyes

Query parameters

FieldTypeRequiredDescription
source_uidstringnoLimit to one source document.
column_namestringnoLimit to one field.

Response 200 — Highlights.

FieldTypeDescription
successboolean
resultobject
result.table_idstring
result.source_uidstring
result.filenamestring
result.file_pathstring
result.file_urlstring
result.highlightsobject[]
result.highlights[].column_namestring
result.highlights[].valueany
result.highlights[].quotestring
result.highlights[].statusstring ("anchored", "unanchored", "no_evidence")
result.highlights[].spansobject[]
result.highlights[].spans[].pageinteger
result.highlights[].spans[].rectnumber[]
result.highlights[].page_widthnumber
result.highlights[].page_heightnumber
result.highlights[].scorenumber
result.highlights[].ambiguousboolean
json
{
  "success": true,
  "result": {
    "table_id": "tbl_9f8e7d6c",
    "source_uid": "1b6c1c1e-9d0a-4b6e-9f2a-3c4d5e6f7a8b",
    "filename": "invoice-1042.pdf",
    "file_path": "/media/Acme/semantic-search/jane/invoice-1042.pdf",
    "file_url": "https://api.example.com/media/Acme/semantic-search/jane/invoice-1042.pdf",
    "highlights": [
      {
        "column_name": "invoice_total",
        "value": 1250.5,
        "quote": "Total due: 1,250.50 SAR",
        "status": "anchored",
        "spans": [
          {
            "page": 1,
            "rect": [
              0.62,
              0.71,
              0.88,
              0.73
            ]
          }
        ],
        "page_width": 612,
        "page_height": 792,
        "score": 0.98,
        "ambiguous": false
      }
    ]
  }
}

Response 403 — Not your table.

Example

bash
curl -X GET "https://api.example.com/microservices/data-extractor/table/<table_id>/highlights" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/data-extractor/chat ​

Chat with a table (extractor service)

Direct question-answering over one table by the extractor service (streamed when the service streams). The app now uses POST /microservices/agent/table-chat/ instead.

Auth: Session token

Request body (application/json)

FieldTypeRequiredDescription
table_idstringno
paramsobjectnoService parameters (query, …).

Response 200 — Streamed or JSON answer.

Example

bash
curl -X POST "https://api.example.com/microservices/data-extractor/chat" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/agent/table-chat/ ​

Ask the assistant about a table

The same contract as POST /microservices/agent/chat/ (see Chat AI), bound to one extracted table: table_id is required and authorised (owner or granted), the skill is pinned to the table desk, and the agent can only read and edit that table. Use a fresh conversation_id per table.

Auth: Session token · In the app: Apps → Databases → table → Chat

Query parameters

FieldTypeRequiredDescription
timeoutintegernoDefault: 600.

Request body (application/json)

FieldTypeRequiredDescription
conversation_idstringyes
messagestringyes
table_idstringyes
chat_session_idintegerno
reasoning_effortstringno
json
{
  "conversation_id": "4d3c2b1a-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "message": "Which supplier has the highest total this month?",
  "table_id": "tbl_9f8e7d6c"
}

Response 200 — The agent's reply (see AgentChatReply).

FieldTypeDescription
statusstringcompleted — answer holds the reply. queued — the turn is queued behind another one; the reply will arrive on the ws/chat/{conversation_id} socket. missing_param, clarification, interrupted — the agent needs input; the question is in message.
answerstringThe reply (Markdown).
messagestringThe agent's question when it needs input.
turn_idstring
queue_positioninteger
mgidstringPresent when the turn produced a dashboard chart (fetch it with GET /microservices/dashboard-data/?mgid=).
dashboard_idstringPresent when the turn published a Studio artifact.
generated_files_urlsstring[]Media URLs of files the turn produced (documents, images). Sign them to download.
json
{
  "status": "completed",
  "turn_id": "7c1f0c1e-2b8f-4a6e-9c0a-1e4b6f2d3a55",
  "answer": "Q3 revenue grew **12.4% year over year**, driven by the enterprise segment (+19%) …\n",
  "generated_files_urls": []
}

Response 400 — table_id missing.

Response 403 — No access to the table.

Example

bash
curl -X POST "https://api.example.com/microservices/agent/table-chat/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"4d3c2b1a-9e8f-4a7b-8c6d-5e4f3a2b1c0d","message":"Which supplier has the highest total this month?","table_id":"tbl_9f8e7d6c"}'

GET /microservices/data-extractor/tables_database ​

List my table databases

Auth: Session token · In the app: Apps → Databases

Query parameters

FieldTypeRequiredDescription
organization_namestringno

Response 200 — Databases (service response).

FieldTypeDescription
countintegerNumber of databases returned.
tables_databasesobject[]
tables_databases[].tables_database_idstring
tables_databases[].namestring
tables_databases[].emailstring
tables_databases[].organization_namestring
tables_databases[].table_idsstring[]
tables_databases[].tables_countinteger
tables_databases[].created_atstring (date-time)
tables_databases[].updated_atstring (date-time)

Example

bash
curl -X GET "https://api.example.com/microservices/data-extractor/tables_database" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/data-extractor/tables_database ​

Create a table database

Auth: Session token

Request body (application/json)

FieldTypeRequiredDescription
namestringyes
table_idsstring[]no
json
{
  "name": "Finance",
  "table_ids": [
    "tbl_9f8e7d6c"
  ]
}

Response 200 — Created (service response with tables_database_id).

FieldTypeDescription
tables_database_idstring
namestring
emailstring
organization_namestring
table_idsstring[]
tables_countinteger
created_atstring (date-time)
updated_atstring (date-time)
json
{
  "tables_database_id": "db_3c2b1a",
  "name": "Finance",
  "email": "jane@acme.com",
  "organization_name": "Acme",
  "table_ids": [
    "tbl_9f8e7d6c"
  ],
  "tables_count": 1,
  "created_at": "2026-09-02T09:00:00Z",
  "updated_at": "2026-09-22T08:05:41Z"
}

Example

bash
curl -X POST "https://api.example.com/microservices/data-extractor/tables_database" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Finance","table_ids":["tbl_9f8e7d6c"]}'

GET /microservices/data-extractor/tables_database/{db_id} ​

Get a table database

Auth: Session token

Path parameters

FieldTypeRequiredDescription
db_idstringyes

Response 200 — The database.

FieldTypeDescription
tables_database_idstring
namestring
emailstring
organization_namestring
table_idsstring[]
tables_countinteger
created_atstring (date-time)
updated_atstring (date-time)
json
{
  "tables_database_id": "db_3c2b1a",
  "name": "Finance",
  "email": "jane@acme.com",
  "organization_name": "Acme",
  "table_ids": [
    "tbl_9f8e7d6c"
  ],
  "tables_count": 1,
  "created_at": "2026-09-02T09:00:00Z",
  "updated_at": "2026-09-22T08:05:41Z"
}

Response 403 — Not yours.

Example

bash
curl -X GET "https://api.example.com/microservices/data-extractor/tables_database/<db_id>" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PUT /microservices/data-extractor/tables_database/{db_id} ​

Rename or re-order a table database

Auth: Session token

Path parameters

FieldTypeRequiredDescription
db_idstringyes

Request body (application/json)

FieldTypeRequiredDescription
namestringno
table_idsstring[]no

Response 200 — Updated.

Example

bash
curl -X PUT "https://api.example.com/microservices/data-extractor/tables_database/<db_id>" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /microservices/data-extractor/tables_database/{db_id} ​

Delete a table database

Deletes the grouping, not the tables.

Auth: Session token

Path parameters

FieldTypeRequiredDescription
db_idstringyes

Response 200 — Deleted.

Example

bash
curl -X DELETE "https://api.example.com/microservices/data-extractor/tables_database/<db_id>" \
  -H "Authorization: Token $FINBLADE_TOKEN"

Finblade documentation