{"openapi":"3.1.0","info":{"title":"BILL Spend and Expense (BYOK) API","version":"0.1.0","description":"BILL Spend and Expense (BYOK) lets an AI assistant read your own BILL Spend and Expense data through the BILL Spend and Expense API with a key you supply (Spend & Expense API token). Read-only: 7 tools (list_budgets, get_budget, list_transactions, get_transaction, list_reimbursements, get_reimbursement, list_users). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-bill-spend-expense.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-bill-spend-expense/docs"},"termsOfService":"https://connectorbay.com/byok-bill-spend-expense/terms"},"servers":[{"url":"https://byok-bill-spend-expense.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-bill-spend-expense/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_budgets":{"post":{"operationId":"list_budgets","summary":"List spend budgets with name, period, limit, per-transaction cap, receipt rule and retired flag. Cursor-paged. Use for \"","description":"List spend budgets with name, period, limit, per-transaction cap, receipt rule and retired flag. Cursor-paged. Use for \"Which budgets are set up in BILL Spend & Expense\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"max":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (1 to 100).","title":"Max"},"next_page":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Page token: the nextPage value of the previous answer, to fetch the following page.","title":"Next Page"},"filters":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Filter, format field:op:value separated by commas. Fields: isBudgetGroup (eq true/false), budgetIds (eq/in), parentBudgetId (eq), name (eq/sw), retired (eq true/false). Example: retired:eq:false.","title":"Filters"}},"title":"list_budgetsArguments","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_budget":{"post":{"operationId":"get_budget","summary":"Get one budget by id: name, period, limit, per-transaction cap and receipt rule. Use for \"Show BILL budget bud_1\".","description":"Get one budget by id: name, period, limit, per-transaction cap and receipt rule. Use for \"Show BILL budget bud_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"budget_id":{"description":"BILL budget id.","maxLength":200,"title":"Budget Id","type":"string"}},"required":["budget_id"],"title":"get_budgetArguments","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_transactions":{"post":{"operationId":"list_transactions","summary":"List card transactions with time, merchant, amount, fees, status, budget, user and receipt status. Pages hold up to 50. ","description":"List card transactions with time, merchant, amount, fees, status, budget, user and receipt status. Pages hold up to 50. Use for \"What card spending did we have this week in BILL Spend & Expense\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"max":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (1 to 50).","title":"Max"},"next_page":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Page token: the nextPage value of the previous answer, to fetch the following page.","title":"Next Page"},"sort":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"One sort field and order as field:order, e.g. occurredTime:desc. Fields: amount, merchantName, occurredTime.","title":"Sort"},"filters":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Filter, format field:op:value separated by commas. Fields include budgetId (eq/in), userId (eq/in), cardId (eq/in), merchantName (eq), fees (lte/gte). Example: budgetId:eq:abc.","title":"Filters"}},"title":"list_transactionsArguments","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_transaction":{"post":{"operationId":"get_transaction","summary":"Get one card transaction by id with merchant, amount, fees, status, budget, user and receipt status. Use for \"Show BILL ","description":"Get one card transaction by id with merchant, amount, fees, status, budget, user and receipt status. Use for \"Show BILL transaction tx_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"transaction_id":{"description":"BILL transaction id.","maxLength":200,"title":"Transaction Id","type":"string"}},"required":["transaction_id"],"title":"get_transactionArguments","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_reimbursements":{"post":{"operationId":"list_reimbursements","summary":"List out-of-pocket reimbursement requests with amount, merchant, note, submitted date, status, type and budget. Use for ","description":"List out-of-pocket reimbursement requests with amount, merchant, note, submitted date, status, type and budget. Use for \"Which reimbursements are pending in BILL Spend & Expense\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"max":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (1 to 100).","title":"Max"},"next_page":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Page token: the nextPage value of the previous answer, to fetch the following page.","title":"Next Page"},"filters":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Filter, format field:op:value separated by commas. Fields include budgetIds (eq/in), userIds (eq/in), type (eq PURCHASE or MILEAGE), submittedTime (lte/gte), retired (eq true/false).","title":"Filters"}},"title":"list_reimbursementsArguments","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_reimbursement":{"post":{"operationId":"get_reimbursement","summary":"Get one reimbursement by id with amount, merchant, note, dates, status, type, budget and user. Use for \"Show BILL reimbu","description":"Get one reimbursement by id with amount, merchant, note, dates, status, type, budget and user. Use for \"Show BILL reimbursement re_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"reimbursement_id":{"description":"BILL reimbursement id.","maxLength":200,"title":"Reimbursement Id","type":"string"}},"required":["reimbursement_id"],"title":"get_reimbursementArguments","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_users":{"post":{"operationId":"list_users","summary":"List Spend & Expense users with id, name, role, retired flag and creation time (no contact or birth details). Use for \"W","description":"List Spend & Expense users with id, name, role, retired flag and creation time (no contact or birth details). Use for \"Who are the users in BILL Spend & Expense\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"max":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results per page (1 to 100).","title":"Max"},"next_page":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Page token: the nextPage value of the previous answer, to fetch the following page.","title":"Next Page"},"filters":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Filter, e.g. retired:eq:true to list only retired users.","title":"Filters"}},"title":"list_usersArguments","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}}}}