My Data — data sources

External data the platform can read on the user's behalf: SharePoint / OneDrive files (Microsoft Graph), SQL databases (stored credentials and the SQL chat), reusable data sources for apps and workflows, live camera/JSON feeds for dashboards, and prompt templates.

Endpoints

Method	Path	Purpose
GET	/ms-graph/graph/auth-url/{domain}/	Start connecting SharePoint/OneDrive
POST	/ms-graph/graph/token-exchange/	Finish connecting SharePoint/OneDrive
POST	/ms-graph/graph/refresh-token/	Refresh Graph tokens
POST	/ms-graph/graph/disconnect/	Disconnect SharePoint/OneDrive
POST	/ms-graph/graph/list-files/	Pull the drive listing from Microsoft
GET	/ms-graph/graph/cached-list/	Browse the cached drive listing
POST	/ms-graph/graph/batch-download-files/	Import drive files into My Data
POST	/ms-graph/graph/download-file/	Get a temporary download URL for a drive item
POST	/ms-graph/graph/forget-file/	Remove an imported drive file
POST	/ms-graph/graph/drive-item-permissions/	Permissions of a drive item
POST	/ms-graph/graph/organization-credentials/	Store an organisation's Microsoft app for Graph
GET	/sql-search/credentials/	List my SQL connections
POST	/sql-search/credentials/	Save a SQL connection
GET	/sql-search/credentials/{id}/	Get a SQL connection
PUT	/sql-search/credentials/{id}/	Update a SQL connection
DELETE	/sql-search/credentials/{id}/	Delete a SQL connection
POST	/sql-search/overview/	Sample rows from every table
POST	/sql-search/chat/	Ask a question of a SQL database
GET	/sql-search/	My SQL chat history
POST	/sql-search/check-connection/	Test a saved SQL connection
POST	/sql-search/fetch-files/	Scan a SQL table for document records
GET	/sql-search/files/	File records found in a SQL table
POST	/sql-search/download-files/	Import file records as documents
GET	/sql-search/files/content/{file_id}/	Raw content of a file record
DELETE	/sql-search/files/{file_id}/	Delete an imported file record
GET	/data-sources/	List data sources
POST	/data-sources/	Create a data source
GET	/data-sources/{id}/	Get a data source
PUT	/data-sources/{id}/	Update a data source
DELETE	/data-sources/{id}/	Delete a data source
POST	/data-sources/{id}/test/	Test the connection
GET	/data-sources/{id}/tables/	Tables exposed by the connection
GET	/data-sources/{id}/columns/	Columns of a table
POST	/data-sources/{id}/preview/	Preview rows
GET	/live-feeds/sources/	List live feeds
POST	/live-feeds/sources/	Create a live feed
GET	/live-feeds/sources/{id}/	Get a live feed
PUT	/live-feeds/sources/{id}/	Update a live feed
DELETE	/live-feeds/sources/{id}/	Delete a live feed
POST	/live-feeds/sources/{id}/test/	Test a live feed
GET	/live-feeds/sources/{id}/proxy/	Fetch JSON through a live feed
POST	/live-feeds/sources/{id}/stream-url/	Get a signed URL for a camera stream
GET	/live-feeds/sources/{id}/stream/	Relay a camera stream
GET	/templates/	List prompt templates
POST	/templates/	Create a prompt template
GET	/templates/{id}/	Get a template
PUT	/templates/{id}/	Update a template
DELETE	/templates/{id}/	Delete a template

GET /ms-graph/graph/auth-url/{domain}/

Start connecting SharePoint/OneDrive

Builds the Microsoft consent URL for the Graph scopes the importer needs (Files.Read, Sites.ReadWrite.All, mail scopes). Credentials come from the organisation matching domain, or — for users with a personal organisation — from their own metadata. After consent Microsoft redirects to redirect_uri with a code; exchange it with token-exchange/.

Auth: Session token · In the app: My Data → SharePoint → Connect

Path parameters

Field	Type	Required	Description
domain	string	yes

Query parameters

Field	Type	Required	Description
redirect_uri	string (uri)	yes	Must be registered on the Azure application.
force_account	boolean	no	Force the account picker.
login_hint	string	no	Pre-select this Microsoft account.

Response 200 — Consent URL.

Field	Type	Description
auth_url	string (uri)

Response 404 — No Microsoft credentials for the domain / account.

{
  "detail": "Organization not found or Microsoft credentials not configured.",
  "domain": "acme.com"
}

Example

curl -X GET "https://api.example.com/ms-graph/graph/auth-url/acme.com/?redirect_uri=https%3A%2F%2Fapp.example.com%2Fconnections-callback" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /ms-graph/graph/token-exchange/

Finish connecting SharePoint/OneDrive

Exchanges the code for Graph tokens, stores them on the user (encrypted) and returns them so the browser can call the drive endpoints. Switching to a different Microsoft account clears the cached drive listing.

Auth: Session token · In the app: /connections-callback page

Request body (application/json)

Field	Type	Required	Description
code	string	yes
domain	string	yes
redirect_uri	string (uri)	yes	The same value used in auth-url.

Response 200 — Tokens.

Field	Type	Description
access_token	string
refresh_token	string
expires_in	integer
scope	string
microsoft_email	string, nullable

Response 400 — Missing code/domain, or Microsoft rejected the exchange.

{
  "detail": "Authentication credentials were not provided."
}

Response 404 — No Microsoft credentials for the domain.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X POST "https://api.example.com/ms-graph/graph/token-exchange/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /ms-graph/graph/refresh-token/

Refresh Graph tokens

Auth: Session token · In the app: Automatic when the Graph token expires

Request body (application/json)

Field	Type	Required	Description
refresh_token	string	yes
domain	string	yes

Response 200 — New tokens.

Field	Type	Description
access_token	string
refresh_token	string
expires_in	integer

Response 400 — Refresh failed.

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/ms-graph/graph/refresh-token/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /ms-graph/graph/disconnect/

Disconnect SharePoint/OneDrive

Forgets the stored Graph tokens and the cached drive listing. Imported documents are kept.

Auth: Session token · In the app: My Data → SharePoint → Disconnect

Response 200 — Disconnected.

Field	Type	Description
detail	string	Human-readable explanation.
code	string	Machine-readable error code (present on some responses).

{
  "detail": "Microsoft cloud disconnected."
}

Example

curl -X POST "https://api.example.com/ms-graph/graph/disconnect/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /ms-graph/graph/list-files/

Pull the drive listing from Microsoft

Walks the whole OneDrive recursively, caches every item, and returns the tree. Slow on large drives; the app calls it once per connect/refresh and browses the cache afterwards.

Auth: Session token · In the app: My Data → SharePoint → Refresh

Request body (application/json)

Field	Type	Required	Description
access_token	string	yes	Graph access token.

Response 200 — Tree of items (children on folders) and the total size.

Field	Type	Description
drive_contents	object[]
total_size_mb	number

Response 400 — access_token missing.

{
  "detail": "Authentication credentials were not provided."
}

Response 500 — Graph error (body carries the Graph response).

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/ms-graph/graph/list-files/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /ms-graph/graph/cached-list/

Browse the cached drive listing

Auth: Session token · In the app: My Data → SharePoint tab

Response 200 — Flat list of cached items with import state.

Field	Type	Description
drive_contents	object[]
drive_contents[].id	string	Graph drive-item id.
drive_contents[].name	string
drive_contents[].type	string ("file", "folder")
drive_contents[].file_extension	string, nullable	MIME type (Graph's file.mimeType); null for folders.
drive_contents[].parent_reference	string	Graph parent path.
drive_contents[].size_bytes	integer
drive_contents[].size_mb	number
drive_contents[].downloaded	boolean
drive_contents[].embedded	boolean
drive_contents[].document_uid	string, nullable	The semantic-search document created from this item, if imported.
drive_contents[].created_at	string (date-time)
drive_contents[].last_modified_at	string (date-time)

Example

curl -X GET "https://api.example.com/ms-graph/graph/cached-list/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /ms-graph/graph/batch-download-files/

Import drive files into My Data

Downloads the selected items and indexes them as semantic-search documents in the background. Items already imported are reported in saved_files; items another user is still processing in in_progress.

Auth: Session token · In the app: My Data → SharePoint → Import selected

Request body (application/json)

Field	Type	Required	Description
access_token	string	yes
file_ids	string[]	yes

Response 200 — Nothing new to import.

Response 202 — Import queued.

Field	Type	Description
saved_files	string[]	Media paths already imported.
in_progress	string[]
batch_id	string, nullable	Poll with semantic-search/upload/batch/{batch_id}/status/.
queued	integer

Response 400 — Missing fields.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X POST "https://api.example.com/ms-graph/graph/batch-download-files/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /ms-graph/graph/download-file/

Get a temporary download URL for a drive item

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
access_token	string	yes
file_id	string	yes

Response 200 — Pre-authenticated Microsoft download URL (short-lived).

Field	Type	Description
download_url	string (uri)

Response 400 — Missing fields, or Graph returned no download URL.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X POST "https://api.example.com/ms-graph/graph/download-file/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /ms-graph/graph/forget-file/

Remove an imported drive file

If you own the imported document its index, file and row are removed; if it was shared with you, you are detached from it. The cached item is marked not imported.

Auth: Session token · In the app: My Data → SharePoint → Remove from My Data

Request body (application/json)

Field	Type	Required	Description
file_id	string	yes

Response 200 — Forgotten.

Field	Type	Description
detail	string
file_id	string

Example

curl -X POST "https://api.example.com/ms-graph/graph/forget-file/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /ms-graph/graph/drive-item-permissions/

Permissions of a drive item

Proxies Graph's permissions collection for one item.

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
access_token	string	yes
drive_item_id	string	yes

Response 200 — Graph permissions response.

Example

curl -X POST "https://api.example.com/ms-graph/graph/drive-item-permissions/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /ms-graph/graph/organization-credentials/

Store an organisation's Microsoft app for Graph

Creates or updates the organisation's Azure application id and secret used for SharePoint access (and Microsoft SSO).

Auth: Session token · In the app: My Data → SharePoint → configure organisation (admins)

Request body (application/json)

Field	Type	Required	Description
domain	string	yes
application_id	string	yes
secret_key	string	yes
organization_name	string	no

Response 200 — Updated.

Field	Type	Description
detail	string
organization	object
organization.id	integer
organization.name	string
organization.domain	string

Response 201 — Created.

Response 400 — Missing fields.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X POST "https://api.example.com/ms-graph/graph/organization-credentials/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /sql-search/credentials/

List my SQL connections

Auth: Session token · In the app: Database search page → connections

Response 200 — Connections.

Array of:

Field	Type	Description
id	integer
connection	string ("mysql", "mariadb", "mssql")	Database engine.
server	string	Host (and port) of the database server.
username	string
password	string	Stored and echoed back — treat this endpoint as sensitive.
database	string
created_at	string (date-time)

Example

curl -X GET "https://api.example.com/sql-search/credentials/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /sql-search/credentials/

Save a SQL connection

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
connection	string ("mysql", "mariadb", "mssql")	yes
server	string	yes
username	string	yes
password	string	yes
database	string	yes

{
  "connection": "mysql",
  "server": "db.internal:3306",
  "username": "reporting",
  "password": "s3cret",
  "database": "erp"
}

Response 200 — Stored ("stored").

Response 400 — Validation errors.

{
  "username": [
    "A user with that username already exists."
  ]
}

Example

curl -X POST "https://api.example.com/sql-search/credentials/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"connection":"mysql","server":"db.internal:3306","username":"reporting","password":"s3cret","database":"erp"}'

GET /sql-search/credentials/{id}/

Get a SQL connection

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 200 — The connection.

Field	Type	Description
id	integer
connection	string ("mysql", "mariadb", "mssql")	Database engine.
server	string	Host (and port) of the database server.
username	string
password	string	Stored and echoed back — treat this endpoint as sensitive.
database	string
created_at	string (date-time)

{
  "id": 3,
  "connection": "mysql",
  "server": "db.internal:3306",
  "username": "reporting",
  "password": "********",
  "database": "erp",
  "created_at": "2026-05-11T08:00:00Z"
}

Response 404 — Not yours.

Example

curl -X GET "https://api.example.com/sql-search/credentials/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PUT /sql-search/credentials/{id}/

Update a SQL connection

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Request body (application/json)

Field	Type	Required	Description
id	integer	no
connection	string ("mysql", "mariadb", "mssql")	no	Database engine.
server	string	no	Host (and port) of the database server.
username	string	no
password	string	no	Stored and echoed back — treat this endpoint as sensitive.
database	string	no
created_at	string (date-time)	no

{
  "id": 3,
  "connection": "mysql",
  "server": "db.internal:3306",
  "username": "reporting",
  "password": "********",
  "database": "erp",
  "created_at": "2026-05-11T08:00:00Z"
}

Response 200 — Updated.

Field	Type	Description
id	integer
connection	string ("mysql", "mariadb", "mssql")	Database engine.
server	string	Host (and port) of the database server.
username	string
password	string	Stored and echoed back — treat this endpoint as sensitive.
database	string
created_at	string (date-time)

{
  "id": 3,
  "connection": "mysql",
  "server": "db.internal:3306",
  "username": "reporting",
  "password": "********",
  "database": "erp",
  "created_at": "2026-05-11T08:00:00Z"
}

Response 400 — Validation errors.

{
  "username": [
    "A user with that username already exists."
  ]
}

Example

curl -X PUT "https://api.example.com/sql-search/credentials/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":3,"connection":"mysql","server":"db.internal:3306","username":"reporting","password":"********","database":"erp","created_at":"2026-05-11T08:00:00Z"}'

DELETE /sql-search/credentials/{id}/

Delete a SQL connection

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 204 — Deleted.

Response 404 — Not yours.

Example

curl -X DELETE "https://api.example.com/sql-search/credentials/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /sql-search/overview/

Sample rows from every table

Connects with the supplied credentials and returns up to limit rows from each table — used to preview a database before chatting with it.

Auth: Session token · In the app: Database search page → Overview

Request body (application/json)

Field	Type	Required	Description
connection	string ("mysql", "mssql")	yes
server	string	yes
username	string	yes
password	string	yes
database	string	yes
limit	integer	yes	Rows per table.

Response 200 — Rows keyed by table name.

Field	Type	Description
result	object

Response 400 — Invalid limit.

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/sql-search/overview/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /sql-search/chat/

Ask a question of a SQL database

Text-to-SQL over the supplied connection. The connection is cached per user for the conversation; both question and answer are stored in the SQL chat history.

Auth: Session token · In the app: Database search page → SQL chat

Request body (application/json)

Field	Type	Required	Description
connection	string ("mysql", "mssql")	yes
server	string	yes
username	string	yes
password	string	yes
database	string	yes
question	string	yes

Response 200 — Answer.

Field	Type	Description
answer	string

Example

curl -X POST "https://api.example.com/sql-search/chat/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /sql-search/

My SQL chat history

Auth: Session token

Response 200 — Messages.

Array of:

Field	Type	Description
id	integer
user	integer
message	string
from_server	boolean
created_at	string (date-time)

Example

curl -X GET "https://api.example.com/sql-search/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /sql-search/check-connection/

Test a saved SQL connection

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
credential_id	integer	yes

Response 200 — Connected.

Field	Type	Description
success	string

Response 404 — Credential not found.

{
  "error": "path is required"
}

Response 500 — Connection failed (body carries the driver error).

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/sql-search/check-connection/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /sql-search/fetch-files/

Scan a SQL table for document records

For document-management databases: reads rows from the credential's configured table (using its id_column, created_at_column, … mapping set by an administrator) and registers each as a file record that can later be downloaded and indexed.

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
credential_id	integer	yes
batch_size	integer	no	Default: 1000.
max_records	integer	no	0 = no limit. Default: 0.

Response 200 — Scan summary.

Field	Type	Description
success	string
saved	integer
skipped	integer
total_fetched	integer
final_offset	integer

Response 400 — Missing credential id or column mapping.

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/sql-search/fetch-files/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /sql-search/files/

File records found in a SQL table

Auth: Session token

Query parameters

Field	Type	Required	Description
credential_id	integer	yes
downloaded	boolean	no
embedded	boolean	no
file_id	integer	no

Response 200 — Column mapping and records.

Field	Type	Description
headers	object	The credential's column mapping.
files	object[]
files[].file_id	integer
files[].doc_in	string, nullable
files[].doc_out	string, nullable
files[].remarks	string, nullable
files[].created_at_original	string, nullable
files[].created_at_hijiri	string, nullable
files[].downloaded	boolean
files[].embedded	boolean
files[].created_at	string (date-time)

Example

curl -X GET "https://api.example.com/sql-search/files/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /sql-search/download-files/

Import file records as documents

Downloads the content of the given records from the database and queues them for indexing in the semantic-search store.

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
credential_id	integer	yes
file_ids	integer[]	yes

Response 202 — Queued.

Field	Type	Description
batch_id	string
queued	integer

Example

curl -X POST "https://api.example.com/sql-search/download-files/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /sql-search/files/content/{file_id}/

Raw content of a file record

Auth: Session token

Path parameters

Field	Type	Required	Description
file_id	integer	yes

Query parameters

Field	Type	Required	Description
credential_id	integer	yes

Response 200 — Content.

Field	Type	Description
content	string

Example

curl -X GET "https://api.example.com/sql-search/files/content/<file_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /sql-search/files/{file_id}/

Delete an imported file record

Auth: Session token

Path parameters

Field	Type	Required	Description
file_id	integer	yes

Response 200 — Deleted.

Response 404 — Not found.

Example

curl -X DELETE "https://api.example.com/sql-search/files/<file_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /data-sources/

List data sources

Connections you own plus those shared with you, newest first.

Auth: Session token · In the app: My Data → Data sources

Response 200 — Data sources.

Array of:

Field	Type	Description
id	integer
name	string
engine	string ("postgresql", "mysql", "mariadb", "mssql")
host	string	Must pass the deployment's host policy (no private/loopback ranges unless allowed).
port	integer, nullable	Defaults to the engine's standard port.
database	string
username	string
password	string	Write-only. Omit on update to keep; send "" to clear.
has_password	boolean
options	object	Driver options (e.g. {"sslmode": "require"}).
allowed_tables	string[]	Restrict the connection to these tables (empty = all).
max_rows	integer	Row cap for queries.
shared	integer[]	User ids the connection is shared with.
credential_version	integer	Increments when credentials change.
last_tested_at	string (date-time), nullable
last_test_ok	boolean, nullable
last_error	string
created_at	string (date-time)
updated_at	string (date-time)
user	integer	Owner id.

Example

curl -X GET "https://api.example.com/data-sources/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /data-sources/

Create a data source

Auth: Session token · In the app: My Data → Data sources → New connection

Request body (application/json)

Field	Type	Required	Description
id	integer	no
name	string	no
engine	string ("postgresql", "mysql", "mariadb", "mssql")	no
host	string	no	Must pass the deployment's host policy (no private/loopback ranges unless allowed).
port	integer, nullable	no	Defaults to the engine's standard port.
database	string	no
username	string	no
password	string	no	Write-only. Omit on update to keep; send "" to clear.
has_password	boolean	no
options	object	no	Driver options (e.g. {"sslmode": "require"}).
allowed_tables	string[]	no	Restrict the connection to these tables (empty = all).
max_rows	integer	no	Row cap for queries.
shared	integer[]	no	User ids the connection is shared with.
credential_version	integer	no	Increments when credentials change.
last_tested_at	string (date-time), nullable	no
last_test_ok	boolean, nullable	no
last_error	string	no
created_at	string (date-time)	no
updated_at	string (date-time)	no
user	integer	no	Owner id.

{
  "name": "Warehouse (read-only)",
  "engine": "postgresql",
  "host": "warehouse.acme.internal",
  "port": 5432,
  "database": "analytics",
  "username": "readonly",
  "password": "s3cret",
  "allowed_tables": [
    "orders",
    "customers"
  ],
  "max_rows": 5000
}

Response 201 — Created.

Field	Type	Description
id	integer
name	string
engine	string ("postgresql", "mysql", "mariadb", "mssql")
host	string	Must pass the deployment's host policy (no private/loopback ranges unless allowed).
port	integer, nullable	Defaults to the engine's standard port.
database	string
username	string
password	string	Write-only. Omit on update to keep; send "" to clear.
has_password	boolean
options	object	Driver options (e.g. {"sslmode": "require"}).
allowed_tables	string[]	Restrict the connection to these tables (empty = all).
max_rows	integer	Row cap for queries.
shared	integer[]	User ids the connection is shared with.
credential_version	integer	Increments when credentials change.
last_tested_at	string (date-time), nullable
last_test_ok	boolean, nullable
last_error	string
created_at	string (date-time)
updated_at	string (date-time)
user	integer	Owner id.

{
  "id": 7,
  "name": "Warehouse (read-only)",
  "engine": "postgresql",
  "host": "warehouse.acme.internal",
  "port": 5432,
  "database": "analytics",
  "username": "readonly",
  "has_password": true,
  "options": {
    "sslmode": "require"
  },
  "allowed_tables": [
    "orders",
    "customers"
  ],
  "max_rows": 5000,
  "shared": [
    57
  ],
  "credential_version": 2,
  "last_tested_at": "2026-09-20T09:00:00Z",
  "last_test_ok": true,
  "last_error": "",
  "created_at": "2026-06-01T09:00:00Z",
  "updated_at": "2026-09-20T09:00:00Z",
  "user": 42
}

Response 400 — Validation errors (including host policy).

{
  "host": [
    "Private network hosts are not allowed."
  ]
}

Example

curl -X POST "https://api.example.com/data-sources/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Warehouse (read-only)","engine":"postgresql","host":"warehouse.acme.internal","port":5432,"database":"analytics","username":"readonly","password":"s3cret","allowed_tables":["orders","customers"],"max_rows":5000}'

GET /data-sources/{id}/

Get a data source

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 200 — The data source.

Field	Type	Description
id	integer
name	string
engine	string ("postgresql", "mysql", "mariadb", "mssql")
host	string	Must pass the deployment's host policy (no private/loopback ranges unless allowed).
port	integer, nullable	Defaults to the engine's standard port.
database	string
username	string
password	string	Write-only. Omit on update to keep; send "" to clear.
has_password	boolean
options	object	Driver options (e.g. {"sslmode": "require"}).
allowed_tables	string[]	Restrict the connection to these tables (empty = all).
max_rows	integer	Row cap for queries.
shared	integer[]	User ids the connection is shared with.
credential_version	integer	Increments when credentials change.
last_tested_at	string (date-time), nullable
last_test_ok	boolean, nullable
last_error	string
created_at	string (date-time)
updated_at	string (date-time)
user	integer	Owner id.

{
  "id": 7,
  "name": "Warehouse (read-only)",
  "engine": "postgresql",
  "host": "warehouse.acme.internal",
  "port": 5432,
  "database": "analytics",
  "username": "readonly",
  "has_password": true,
  "options": {
    "sslmode": "require"
  },
  "allowed_tables": [
    "orders",
    "customers"
  ],
  "max_rows": 5000,
  "shared": [
    57
  ],
  "credential_version": 2,
  "last_tested_at": "2026-09-20T09:00:00Z",
  "last_test_ok": true,
  "last_error": "",
  "created_at": "2026-06-01T09:00:00Z",
  "updated_at": "2026-09-20T09:00:00Z",
  "user": 42
}

Response 403 — Not shared with you.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X GET "https://api.example.com/data-sources/7/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PUT /data-sources/{id}/

Update a data source

Owner only; partial update. Rotating credentials or narrowing shared revokes outstanding agent grants.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Request body (application/json)

Field	Type	Required	Description
id	integer	no
name	string	no
engine	string ("postgresql", "mysql", "mariadb", "mssql")	no
host	string	no	Must pass the deployment's host policy (no private/loopback ranges unless allowed).
port	integer, nullable	no	Defaults to the engine's standard port.
database	string	no
username	string	no
password	string	no	Write-only. Omit on update to keep; send "" to clear.
has_password	boolean	no
options	object	no	Driver options (e.g. {"sslmode": "require"}).
allowed_tables	string[]	no	Restrict the connection to these tables (empty = all).
max_rows	integer	no	Row cap for queries.
shared	integer[]	no	User ids the connection is shared with.
credential_version	integer	no	Increments when credentials change.
last_tested_at	string (date-time), nullable	no
last_test_ok	boolean, nullable	no
last_error	string	no
created_at	string (date-time)	no
updated_at	string (date-time)	no
user	integer	no	Owner id.

{
  "id": 7,
  "name": "Warehouse (read-only)",
  "engine": "postgresql",
  "host": "warehouse.acme.internal",
  "port": 5432,
  "database": "analytics",
  "username": "readonly",
  "has_password": true,
  "options": {
    "sslmode": "require"
  },
  "allowed_tables": [
    "orders",
    "customers"
  ],
  "max_rows": 5000,
  "shared": [
    57
  ],
  "credential_version": 2,
  "last_tested_at": "2026-09-20T09:00:00Z",
  "last_test_ok": true,
  "last_error": "",
  "created_at": "2026-06-01T09:00:00Z",
  "updated_at": "2026-09-20T09:00:00Z",
  "user": 42
}

Response 200 — Updated.

Field	Type	Description
id	integer
name	string
engine	string ("postgresql", "mysql", "mariadb", "mssql")
host	string	Must pass the deployment's host policy (no private/loopback ranges unless allowed).
port	integer, nullable	Defaults to the engine's standard port.
database	string
username	string
password	string	Write-only. Omit on update to keep; send "" to clear.
has_password	boolean
options	object	Driver options (e.g. {"sslmode": "require"}).
allowed_tables	string[]	Restrict the connection to these tables (empty = all).
max_rows	integer	Row cap for queries.
shared	integer[]	User ids the connection is shared with.
credential_version	integer	Increments when credentials change.
last_tested_at	string (date-time), nullable
last_test_ok	boolean, nullable
last_error	string
created_at	string (date-time)
updated_at	string (date-time)
user	integer	Owner id.

{
  "id": 7,
  "name": "Warehouse (read-only)",
  "engine": "postgresql",
  "host": "warehouse.acme.internal",
  "port": 5432,
  "database": "analytics",
  "username": "readonly",
  "has_password": true,
  "options": {
    "sslmode": "require"
  },
  "allowed_tables": [
    "orders",
    "customers"
  ],
  "max_rows": 5000,
  "shared": [
    57
  ],
  "credential_version": 2,
  "last_tested_at": "2026-09-20T09:00:00Z",
  "last_test_ok": true,
  "last_error": "",
  "created_at": "2026-06-01T09:00:00Z",
  "updated_at": "2026-09-20T09:00:00Z",
  "user": 42
}

Response 403 — Not the owner.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X PUT "https://api.example.com/data-sources/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":7,"name":"Warehouse (read-only)","engine":"postgresql","host":"warehouse.acme.internal","port":5432,"database":"analytics","username":"readonly","has_password":true,"options":{"sslmode":"require"},"allowed_tables":["orders","customers"],"max_rows":5000,"shared":[57],"credential_version":2,"last_tested_at":"2026-09-20T09:00:00Z","last_test_ok":true,"last_error":"","created_at":"2026-06-01T09:00:00Z","updated_at":"2026-09-20T09:00:00Z","user":42}'

DELETE /data-sources/{id}/

Delete a data source

Owner only. Refused with 409 while dashboard tiles use it, unless force=1.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Query parameters

Field	Type	Required	Description
force	boolean	no

Response 200 — Deleted.

Field	Type	Description
message	string

{
  "message": "OK"
}

Response 409 — In use by dashboard tiles.

{
  "error": "This connection is used by dashboard tiles.",
  "in_use": [
    {
      "id": 91,
      "chart_name": "Orders by month",
      "category_id": 3
    }
  ]
}

Example

curl -X DELETE "https://api.example.com/data-sources/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /data-sources/{id}/test/

Test the connection

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 200 — Always 200; read ok.

Field	Type	Description
ok	boolean
latency_ms	integer, nullable
error	string

{
  "ok": true,
  "latency_ms": 38,
  "error": ""
}

Example

curl -X POST "https://api.example.com/data-sources/<id>/test/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /data-sources/{id}/tables/

Tables exposed by the connection

Cached for 5 minutes; refresh=1 forces a new read. Honours allowed_tables.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Query parameters

Field	Type	Required	Description
refresh	boolean	no

Response 200 — Tables.

Field	Type	Description
tables	object[]
tables[].name	string
tables[].schema	string

{
  "tables": [
    {
      "name": "orders",
      "schema": "public"
    },
    {
      "name": "customers",
      "schema": "public"
    }
  ]
}

Response 502 — The SQL service could not run the query.

{
  "error": "path is required"
}

Example

curl -X GET "https://api.example.com/data-sources/<id>/tables/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /data-sources/{id}/columns/

Columns of a table

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Query parameters

Field	Type	Required	Description
table	string	yes

Response 200 — Columns.

Field	Type	Description
table	string
columns	object[]
columns[].name	string
columns[].type	string

{
  "table": "orders",
  "columns": [
    {
      "name": "id",
      "type": "integer"
    },
    {
      "name": "total",
      "type": "numeric"
    }
  ]
}

Example

curl -X GET "https://api.example.com/data-sources/<id>/columns/?table=orders" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /data-sources/{id}/preview/

Preview rows

Up to 200 rows from a table, or from a read-only SELECT you supply.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Request body (application/json)

Field	Type	Required	Description
table	string	no
sql	string	no	A SELECT statement (alternative to table).

{
  "sql": "SELECT region, SUM(total) AS total FROM orders GROUP BY region"
}

Response 200 — Rows.

Field	Type	Description
columns	string[]
rows	object[]	One object per row, keyed by column.
row_count	integer
truncated	boolean	True when the row cap cut the result.
elapsed_ms	integer

{
  "columns": [
    "id",
    "region",
    "total"
  ],
  "rows": [
    {
      "id": 1,
      "region": "East",
      "total": 1200000
    },
    {
      "id": 2,
      "region": "West",
      "total": 900000
    }
  ],
  "row_count": 2,
  "truncated": false,
  "elapsed_ms": 41
}

Response 400 — Neither table nor sql, or a non-SELECT statement.

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/data-sources/<id>/preview/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT region, SUM(total) AS total FROM orders GROUP BY region"}'

GET /live-feeds/sources/

List live feeds

Auth: Session token · In the app: Dashboard → live tiles

Response 200 — Feeds you own or that are shared with you.

Array of:

Field	Type	Description
id	integer
name	string
base_url	string	Origin plus optional base path; requests are restricted to it.
auth_type	string ("none", "bearer", "header", "query")
auth_header_name	string	For header auth (e.g. X-API-Key).
auth_query_param	string	For query auth (e.g. key).
api_key	string	Accepted on create and update; never returned — read has_api_key instead.
has_api_key	boolean
verify_tls	boolean
shared	integer[]
created_at	string (date-time)
updated_at	string (date-time)
user	integer

Example

curl -X GET "https://api.example.com/live-feeds/sources/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /live-feeds/sources/

Create a live feed

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
id	integer	no
name	string	no
base_url	string	no	Origin plus optional base path; requests are restricted to it.
auth_type	string ("none", "bearer", "header", "query")	no
auth_header_name	string	no	For header auth (e.g. X-API-Key).
auth_query_param	string	no	For query auth (e.g. key).
api_key	string	no	Accepted on create and update; never returned — read has_api_key instead.
has_api_key	boolean	no
verify_tls	boolean	no
shared	integer[]	no
created_at	string (date-time)	no
updated_at	string (date-time)	no
user	integer	no

{
  "name": "Lobby camera",
  "base_url": "https://cams.acme.internal",
  "auth_type": "header",
  "auth_header_name": "X-API-Key",
  "api_key": "s3cret"
}

Response 201 — Created.

Field	Type	Description
id	integer
name	string
base_url	string	Origin plus optional base path; requests are restricted to it.
auth_type	string ("none", "bearer", "header", "query")
auth_header_name	string	For header auth (e.g. X-API-Key).
auth_query_param	string	For query auth (e.g. key).
api_key	string	Accepted on create and update; never returned — read has_api_key instead.
has_api_key	boolean
verify_tls	boolean
shared	integer[]
created_at	string (date-time)
updated_at	string (date-time)
user	integer

{
  "id": 4,
  "name": "Lobby camera",
  "base_url": "https://cams.acme.internal",
  "auth_type": "header",
  "auth_header_name": "X-API-Key",
  "auth_query_param": "",
  "has_api_key": true,
  "verify_tls": true,
  "shared": [],
  "created_at": "2026-07-01T08:00:00Z",
  "updated_at": "2026-07-01T08:00:00Z",
  "user": 42
}

Response 400 — Validation errors.

{
  "username": [
    "A user with that username already exists."
  ]
}

Example

curl -X POST "https://api.example.com/live-feeds/sources/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Lobby camera","base_url":"https://cams.acme.internal","auth_type":"header","auth_header_name":"X-API-Key","api_key":"s3cret"}'

GET /live-feeds/sources/{id}/

Get a live feed

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 200 — The feed.

Field	Type	Description
id	integer
name	string
base_url	string	Origin plus optional base path; requests are restricted to it.
auth_type	string ("none", "bearer", "header", "query")
auth_header_name	string	For header auth (e.g. X-API-Key).
auth_query_param	string	For query auth (e.g. key).
api_key	string	Accepted on create and update; never returned — read has_api_key instead.
has_api_key	boolean
verify_tls	boolean
shared	integer[]
created_at	string (date-time)
updated_at	string (date-time)
user	integer

{
  "id": 4,
  "name": "Lobby camera",
  "base_url": "https://cams.acme.internal",
  "auth_type": "header",
  "auth_header_name": "X-API-Key",
  "auth_query_param": "",
  "has_api_key": true,
  "verify_tls": true,
  "shared": [],
  "created_at": "2026-07-01T08:00:00Z",
  "updated_at": "2026-07-01T08:00:00Z",
  "user": 42
}

Example

curl -X GET "https://api.example.com/live-feeds/sources/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PUT /live-feeds/sources/{id}/

Update a live feed

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Request body (application/json)

Field	Type	Required	Description
id	integer	no
name	string	no
base_url	string	no	Origin plus optional base path; requests are restricted to it.
auth_type	string ("none", "bearer", "header", "query")	no
auth_header_name	string	no	For header auth (e.g. X-API-Key).
auth_query_param	string	no	For query auth (e.g. key).
api_key	string	no	Accepted on create and update; never returned — read has_api_key instead.
has_api_key	boolean	no
verify_tls	boolean	no
shared	integer[]	no
created_at	string (date-time)	no
updated_at	string (date-time)	no
user	integer	no

{
  "id": 4,
  "name": "Lobby camera",
  "base_url": "https://cams.acme.internal",
  "auth_type": "header",
  "auth_header_name": "X-API-Key",
  "auth_query_param": "",
  "has_api_key": true,
  "verify_tls": true,
  "shared": [],
  "created_at": "2026-07-01T08:00:00Z",
  "updated_at": "2026-07-01T08:00:00Z",
  "user": 42
}

Response 200 — Updated.

Field	Type	Description
id	integer
name	string
base_url	string	Origin plus optional base path; requests are restricted to it.
auth_type	string ("none", "bearer", "header", "query")
auth_header_name	string	For header auth (e.g. X-API-Key).
auth_query_param	string	For query auth (e.g. key).
api_key	string	Accepted on create and update; never returned — read has_api_key instead.
has_api_key	boolean
verify_tls	boolean
shared	integer[]
created_at	string (date-time)
updated_at	string (date-time)
user	integer

{
  "id": 4,
  "name": "Lobby camera",
  "base_url": "https://cams.acme.internal",
  "auth_type": "header",
  "auth_header_name": "X-API-Key",
  "auth_query_param": "",
  "has_api_key": true,
  "verify_tls": true,
  "shared": [],
  "created_at": "2026-07-01T08:00:00Z",
  "updated_at": "2026-07-01T08:00:00Z",
  "user": 42
}

Example

curl -X PUT "https://api.example.com/live-feeds/sources/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":4,"name":"Lobby camera","base_url":"https://cams.acme.internal","auth_type":"header","auth_header_name":"X-API-Key","auth_query_param":"","has_api_key":true,"verify_tls":true,"shared":[],"created_at":"2026-07-01T08:00:00Z","updated_at":"2026-07-01T08:00:00Z","user":42}'

DELETE /live-feeds/sources/{id}/

Delete a live feed

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 200 — Deleted.

Field	Type	Description
message	string

{
  "message": "OK"
}

Example

curl -X DELETE "https://api.example.com/live-feeds/sources/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /live-feeds/sources/{id}/test/

Test a live feed

Probes base_url + path. Always answers 200; read ok.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Request body (application/json, optional)

Field	Type	Required	Description
path	string	no	Default: "/".

Response 200 — Probe result.

Field	Type	Description
ok	boolean
url	string
status_code	integer
latency_ms	integer
content_type	string
sample	string, nullable	First 500 characters for text/JSON responses.
error	string

Example

curl -X POST "https://api.example.com/live-feeds/sources/<id>/test/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /live-feeds/sources/{id}/proxy/

Fetch JSON through a live feed

Proxies a GET to base_url + path with the feed's credentials attached server-side (max 5 MB). Extra query parameters are forwarded upstream.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Query parameters

Field	Type	Required	Description
path	string	yes

Response 200 — The upstream JSON (upstream status codes are passed through).

Response 502 — Upstream error.

Response 504 — Upstream timed out.

Example

curl -X GET "https://api.example.com/live-feeds/sources/<id>/proxy/?path=%2Fapi%2Fstatus" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /live-feeds/sources/{id}/stream-url/

Get a signed URL for a camera stream

Mirrors media signing — returns a short-lived URL (default 5 minutes) that can be placed in an <img src> to relay an MJPEG stream or snapshot.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Request body (application/json)

Field	Type	Required	Description
path	string	yes
ttl	integer	no

{
  "path": "/video.mjpg"
}

Response 200 — Signed relative URL.

Field	Type	Description
path	string
url	string	Relative URL (live-feeds/sources/{id}/stream/?…).
expires_at	integer
ttl	integer

Example

curl -X POST "https://api.example.com/live-feeds/sources/<id>/stream-url/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"/video.mjpg"}'

GET /live-feeds/sources/{id}/stream/

Relay a camera stream

Streams the upstream response chunk by chunk. Authenticated only by the signature from stream-url/; at most 12 concurrent relays per API process.

Auth: Signed URL (from stream-url/)

Path parameters

Field	Type	Required	Description
id	integer	yes

Query parameters

Field	Type	Required	Description
path	string	yes
expires_at	integer	yes
user_id	integer	yes
signature	string	yes

Response 200 — The stream (e.g. multipart/x-mixed-replace MJPEG or an image).

Response 403 — Invalid or expired signature.

Response 503 — Relay limit reached.

Example

curl -X GET "https://api.example.com/live-feeds/sources/<id>/stream/"

GET /templates/

List prompt templates

Your templates plus shared (general) ones, optionally filtered by type.

Auth: Session token · In the app: My Data → Templates

Query parameters

Field	Type	Required	Description
type	string	no

Response 200 — Templates.

Array of:

Field	Type	Description
id	integer
user	integer, nullable
type	string	Free-form grouping key, e.g. semantic_search.
title	string
content	string	The prompt text.
general	boolean
created_at	string (date-time)

Example

curl -X GET "https://api.example.com/templates/?type=semantic_search" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /templates/

Create a prompt template

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
title	string	no
content	string	yes
type	string	no
general	boolean	no	Default: false.

{
  "title": "Executive summary",
  "content": "Summarise the document for a board audience in five bullets.",
  "type": "semantic_search"
}

Response 201 — Created.

Field	Type	Description
id	integer
user	integer, nullable
type	string	Free-form grouping key, e.g. semantic_search.
title	string
content	string	The prompt text.
general	boolean
created_at	string (date-time)

{
  "id": 12,
  "user": 42,
  "type": "semantic_search",
  "title": "Executive summary",
  "content": "Summarise the document for a board audience in five bullets.",
  "general": false,
  "created_at": "2026-04-02T10:00:00Z"
}

Response 400 — Validation errors.

{
  "username": [
    "A user with that username already exists."
  ]
}

Example

curl -X POST "https://api.example.com/templates/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Executive summary","content":"Summarise the document for a board audience in five bullets.","type":"semantic_search"}'

GET /templates/{id}/

Get a template

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 200 — The template.

Field	Type	Description
id	integer
user	integer, nullable
type	string	Free-form grouping key, e.g. semantic_search.
title	string
content	string	The prompt text.
general	boolean
created_at	string (date-time)

{
  "id": 12,
  "user": 42,
  "type": "semantic_search",
  "title": "Executive summary",
  "content": "Summarise the document for a board audience in five bullets.",
  "general": false,
  "created_at": "2026-04-02T10:00:00Z"
}

Example

curl -X GET "https://api.example.com/templates/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PUT /templates/{id}/

Update a template

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Request body (application/json)

Field	Type	Required	Description
title	string	no
content	string	no
type	string	no
general	boolean	no

Response 200 — The updatable fields after the change.

Field	Type	Description
template	object
template.title	string
template.content	string
template.type	string
template.general	boolean

Example

curl -X PUT "https://api.example.com/templates/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /templates/{id}/

Delete a template

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 204 — Deleted.

Example

curl -X DELETE "https://api.example.com/templates/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"