{"openapi":"3.1.0","info":{"title":"Mode (BYOK) API","version":"0.1.0","description":"Mode (BYOK) lets an AI assistant read your own Mode data through the Mode API with a key you supply (Mode API token). Read-only: 8 tools (list_collections, get_collection, list_collection_reports, get_report, list_report_runs, get_report_run, list_report_queries, get_query). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-mode.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-mode/docs"},"termsOfService":"https://connectorbay.com/byok-mode/terms"},"servers":[{"url":"https://byok-mode.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-mode/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_collections":{"post":{"operationId":"list_collections","summary":"List the collections (spaces) of a workspace that you can see. Answers are HAL documents; the collections are under _emb","description":"List the collections (spaces) of a workspace that you can see. Answers are HAL documents; the collections are under _embedded. Use for \"Which collections do we have in Mode\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace":{"description":"Workspace username (the part after app.mode.com/), for example acme.","maxLength":100,"title":"Workspace","type":"string"},"filter":{"anyOf":[{"enum":["all","custom"],"type":"string"},{"type":"null"}],"default":null,"description":"all to include other users' personal collections (admins), custom for non-personal collections only.","title":"Filter"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Page number; giving page or per_page makes the answer paginated.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Results per page.","title":"Per Page"}},"required":["workspace"],"title":"list_collectionsArguments","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_collection":{"post":{"operationId":"get_collection","summary":"Get one collection (space): name, description, type, state and whether access is restricted. Use for \"What is in Mode co","description":"Get one collection (space): name, description, type, state and whether access is restricted. Use for \"What is in Mode collection f3gtgvfbghnm\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace":{"description":"Workspace username (the part after app.mode.com/), for example acme.","maxLength":100,"title":"Workspace","type":"string"},"space":{"description":"Collection token (called a space in the API), from list_collections.","maxLength":40,"title":"Space","type":"string"}},"required":["workspace","space"],"title":"get_collectionArguments","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_collection_reports":{"post":{"operationId":"list_collection_reports","summary":"List the reports in a collection, optionally filtered and ordered by creation or update time. The reports are under _emb","description":"List the reports in a collection, optionally filtered and ordered by creation or update time. The reports are under _embedded. Use for \"What reports are in our Mode Marketing collection\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace":{"description":"Workspace username (the part after app.mode.com/), for example acme.","maxLength":100,"title":"Workspace","type":"string"},"space":{"description":"Collection token (called a space in the API), from list_collections.","maxLength":40,"title":"Space","type":"string"},"filter":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Time filter such as created_at.gt.2026-01-01T00:00:00Z or updated_at.lt.<datetime> (gt = after, lt = before).","title":"Filter"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Order"},"order_by":{"anyOf":[{"enum":["created_at","updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by created_at or updated_at.","title":"Order By"}},"required":["workspace","space"],"title":"list_collection_reportsArguments","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_report":{"post":{"operationId":"get_report","summary":"Get one report: name, description, dates, last run times, archived and public flags, and counts of queries, charts, runs","description":"Get one report: name, description, dates, last run times, archived and public flags, and counts of queries, charts, runs, schedules and views. Use for \"When did Mode report d9a0b3c4e5f6 last run successfully\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace":{"description":"Workspace username (the part after app.mode.com/), for example acme.","maxLength":100,"title":"Workspace","type":"string"},"report":{"description":"Report token (from list_collection_reports).","maxLength":40,"title":"Report","type":"string"}},"required":["workspace","report"],"title":"get_reportArguments","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_report_runs":{"post":{"operationId":"list_report_runs","summary":"List the runs of a report with state and timestamps. The runs are under _embedded. Use for \"Did the last Mode runs of my","description":"List the runs of a report with state and timestamps. The runs are under _embedded. Use for \"Did the last Mode runs of my report succeed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace":{"description":"Workspace username (the part after app.mode.com/), for example acme.","maxLength":100,"title":"Workspace","type":"string"},"report":{"description":"Report token (from list_collection_reports).","maxLength":40,"title":"Report","type":"string"},"filter":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Time filter such as created_at.gt.2026-01-01T00:00:00Z or updated_at.lt.<datetime> (gt = after, lt = before).","title":"Filter"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Order"},"order_by":{"anyOf":[{"enum":["created_at","updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by created_at or updated_at.","title":"Order By"}},"required":["workspace","report"],"title":"list_report_runsArguments","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_report_run":{"post":{"operationId":"get_report_run","summary":"Get one report run: state (pending, enqueued, running, succeeded, failed, cancelled), parameters and timing. Use for \"Wh","description":"Get one report run: state (pending, enqueued, running, succeeded, failed, cancelled), parameters and timing. Use for \"Why did this Mode report run fail\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace":{"description":"Workspace username (the part after app.mode.com/), for example acme.","maxLength":100,"title":"Workspace","type":"string"},"report":{"description":"Report token (from list_collection_reports).","maxLength":40,"title":"Report","type":"string"},"run":{"description":"Report run token (from list_report_runs).","maxLength":40,"title":"Run","type":"string"}},"required":["workspace","report","run"],"title":"get_report_runArguments","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_report_queries":{"post":{"operationId":"list_report_queries","summary":"List the SQL queries of a report. The queries are under _embedded. Use for \"What SQL does my Mode report run\".","description":"List the SQL queries of a report. The queries are under _embedded. Use for \"What SQL does my Mode report run\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace":{"description":"Workspace username (the part after app.mode.com/), for example acme.","maxLength":100,"title":"Workspace","type":"string"},"report":{"description":"Report token (from list_collection_reports).","maxLength":40,"title":"Report","type":"string"}},"required":["workspace","report"],"title":"list_report_queriesArguments","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_query":{"post":{"operationId":"get_query","summary":"Get one query of a report: name, SQL text, data source id and last run id. Use for \"Show me the SQL of Mode query hfs8g3","description":"Get one query of a report: name, SQL text, data source id and last run id. Use for \"Show me the SQL of Mode query hfs8g37\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace":{"description":"Workspace username (the part after app.mode.com/), for example acme.","maxLength":100,"title":"Workspace","type":"string"},"report":{"description":"Report token (from list_collection_reports).","maxLength":40,"title":"Report","type":"string"},"query":{"description":"Query token (from list_report_queries).","maxLength":40,"title":"Query","type":"string"}},"required":["workspace","report","query"],"title":"get_queryArguments","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}}}}