{"openapi":"3.1.0","info":{"title":"Databox (BYOK) API","version":"0.1.0","description":"Databox (BYOK) lets an AI assistant read your own Databox data through the Databox API with a key you supply (Databox API key). Read-only: 12 tools (list_accounts, list_data_sources, list_integrations, list_databoards, get_databoard_metrics, list_datasets, get_dataset, get_dataset_sync_history, get_dataset_schema, list_metrics, get_organization_usage, list_activity_log). The BYOK key travels with...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-databox.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-databox/docs"},"termsOfService":"https://connectorbay.com/byok-databox/terms"},"servers":[{"url":"https://byok-databox.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-databox/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_accounts":{"post":{"operationId":"list_accounts","summary":"List the accounts of the organization (id, name, whether self-managed and which account manages it). Use for \"Which acco","description":"List the accounts of the organization (id, name, whether self-managed and which account manages it). Use for \"Which accounts are in my Databox organization\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only accounts whose name contains this text.","title":"Search"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc (default) or desc.","title":"Sort Order"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100, default 25).","title":"Page Size"}},"title":"list_accountsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_data_sources":{"post":{"operationId":"list_data_sources","summary":"List data sources (connected tools such as ad platforms or databases) with integration, status, timezone and last activi","description":"List data sources (connected tools such as ad platforms or databases) with integration, status, timezone and last activity. Use for \"Which data sources are connected in Databox and are any in error\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only data sources whose name contains this text.","title":"Search"},"connection_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only data sources of this connection id.","title":"Connection Id"},"sort_by":{"anyOf":[{"enum":["name","createdAt","lastActivityAt"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by name, createdAt or lastActivityAt.","title":"Sort By"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc (default) or desc.","title":"Sort Order"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100, default 25).","title":"Page Size"}},"title":"list_data_sourcesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_integrations":{"post":{"operationId":"list_integrations","summary":"List the integrations Databox offers (key, name, whether datasets are supported). Use for \"Does Databox have an integrat","description":"List the integrations Databox offers (key, name, whether datasets are supported). Use for \"Does Databox have an integration for HubSpot\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only integrations whose name contains this text.","title":"Search"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc (default) or desc.","title":"Sort Order"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100, default 25).","title":"Page Size"}},"title":"list_integrationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_databoards":{"post":{"operationId":"list_databoards","summary":"List databoards (dashboards) with their tags and the integrations they use. Use for \"What databoards do we have in Datab","description":"List databoards (dashboards) with their tags and the integrations they use. Use for \"What databoards do we have in Databox\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only databoards whose name contains this text.","title":"Search"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100, default 25).","title":"Page Size"}},"title":"list_databoardsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_databoard_metrics":{"post":{"operationId":"get_databoard_metrics","summary":"Show the datablocks of one databoard and the metrics, dimensions, date ranges and filters each one uses. Use for \"Which ","description":"Show the datablocks of one databoard and the metrics, dimensions, date ranges and filters each one uses. Use for \"Which metrics are on my Marketing databoard in Databox\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"databoard_id":{"description":"Id of the databoard (from list_databoards).","title":"Databoard Id","type":"integer"}},"required":["databoard_id"],"title":"get_databoard_metricsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_datasets":{"post":{"operationId":"list_datasets","summary":"List datasets (tables of ingested data) with status, last sync, verification and ingestion info; optionally for one data","description":"List datasets (tables of ingested data) with status, last sync, verification and ingestion info; optionally for one data source. Use for \"Which Databox datasets failed to sync recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"data_source_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only datasets of this data source id.","title":"Data Source Id"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only datasets whose name contains this text.","title":"Search"},"sort_by":{"anyOf":[{"enum":["name","createdAt","lastActivityAt"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by name, createdAt or lastActivityAt.","title":"Sort By"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc (default) or desc.","title":"Sort Order"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100, default 25).","title":"Page Size"}},"title":"list_datasetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_dataset":{"post":{"operationId":"get_dataset","summary":"Get one dataset: status, verification, sync interval in minutes, row and column counts, size and the last sync and inges","description":"Get one dataset: status, verification, sync interval in minutes, row and column counts, size and the last sync and ingestion details. Use for \"How big is Databox dataset 7 and when did it last sync\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Id of the dataset (from list_datasets).","title":"Dataset Id","type":"integer"}},"required":["dataset_id"],"title":"get_datasetArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_dataset_sync_history":{"post":{"operationId":"get_dataset_sync_history","summary":"List the recent sync runs of a dataset with start time, status, type, duration and any error. Use for \"Why did Databox d","description":"List the recent sync runs of a dataset with start time, status, type, duration and any error. Use for \"Why did Databox dataset 7 fail its last sync\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Id of the dataset (from list_datasets).","title":"Dataset Id","type":"integer"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100, default 25).","title":"Page Size"}},"required":["dataset_id"],"title":"get_dataset_sync_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_dataset_schema":{"post":{"operationId":"get_dataset_schema","summary":"Show the columns of a dataset (name, data type, order, visibility) and its primary key. Use for \"What columns does Datab","description":"Show the columns of a dataset (name, data type, order, visibility) and its primary key. Use for \"What columns does Databox dataset 7 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_id":{"description":"Id of the dataset (from list_datasets).","title":"Dataset Id","type":"integer"}},"required":["dataset_id"],"title":"get_dataset_schemaArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_metrics":{"post":{"operationId":"list_metrics","summary":"List metrics available in Databox with their dimensions, drilldown support and verification flag; optionally for one dat","description":"List metrics available in Databox with their dimensions, drilldown support and verification flag; optionally for one data source. Use for \"Which metrics does my Google Analytics data source offer in Databox\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"source_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only metrics of this data source id.","title":"Source Id"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only metrics whose name contains this text.","title":"Search"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100, default 25).","title":"Page Size"}},"title":"list_metricsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_organization_usage":{"post":{"operationId":"get_organization_usage","summary":"Show plan usage against limits: users, data sources, accounts and AI credits used, limit and reset time. Use for \"How cl","description":"Show plan usage against limits: users, data sources, accounts and AI credits used, limit and reset time. Use for \"How close am I to my Databox plan limits\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_organization_usageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_activity_log":{"post":{"operationId":"list_activity_log","summary":"List the organization's activity log (who did what to which resource and when) with optional filters. Use for \"What chan","description":"List the organization's activity log (who did what to which resource and when) with optional filters. Use for \"What changes were made in Databox this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only activity entries whose name contains this text.","title":"Search"},"resource_type":{"anyOf":[{"enum":["administration","billing","connection","dataset","dataSource","metric","user"],"type":"string"},{"type":"null"}],"default":null,"description":"Only entries for this resource type.","title":"Resource Type"},"date_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only entries from this date (ISO 8601).","title":"Date From"},"date_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only entries up to this date (ISO 8601).","title":"Date To"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page (1 to 100, default 25).","title":"Page Size"}},"title":"list_activity_logArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}