{"openapi":"3.1.0","info":{"title":"freee (BYOK) API","version":"0.1.0","description":"freee (BYOK) lets an AI assistant read your own freee data through the freee API with a key you supply (freee OAuth access token (read scope; it expires after a while, so paste a fresh one)). Read-only: 10 tools (list_companies, list_partners, list_account_items, list_deals, list_invoices, get_profit_and_loss, get_balance_sheet, list_walletables, list_wallet_txns, list_sections). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-freee.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-freee/docs"},"termsOfService":"https://connectorbay.com/byok-freee/terms"},"servers":[{"url":"https://byok-freee.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-freee/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_companies":{"post":{"operationId":"list_companies","summary":"List the freee business offices (companies) the token can access, with id, name, display name, corporate number and the ","description":"List the freee business offices (companies) the token can access, with id, name, display name, corporate number and the user's role. Call this first to get company_id. Use for \"Which freee business offices can I read and what are their ids\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_companiesArguments","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_partners":{"post":{"operationId":"list_partners","summary":"List trading partners (customers and suppliers) of a business office with code, name, kana, country and qualified invoic","description":"List trading partners (customers and suppliers) of a business office with code, name, kana, country and qualified invoice issuer number. Filter by keyword or update date; page with offset. Use for \"Which freee partners match the keyword 'Tokyo'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Id of the freee business office (jigyosho), taken from list_companies.","minimum":1,"title":"Company Id","type":"integer"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against partner name and code.","title":"Keyword"},"start_update_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or after this date (YYYY-MM-DD).","title":"Start Update Date"},"end_update_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or before this date (YYYY-MM-DD).","title":"End Update Date"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of rows to skip, for paging (default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":3000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many rows to return (1 to 3000).","title":"Limit"}},"required":["company_id"],"title":"list_partnersArguments","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_account_items":{"post":{"operationId":"list_account_items","summary":"List the account items (chart of accounts) of a business office with id, name, category, default tax code and whether ea","description":"List the account items (chart of accounts) of a business office with id, name, category, default tax code and whether each is available. Use for \"Which account items does my freee business office use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Id of the freee business office (jigyosho), taken from list_companies.","minimum":1,"title":"Company Id","type":"integer"},"base_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Date for which to evaluate availability (YYYY-MM-DD).","title":"Base Date"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against the account item name.","title":"Keyword"},"start_update_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or after this date (YYYY-MM-DD).","title":"Start Update Date"},"end_update_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or before this date (YYYY-MM-DD).","title":"End Update Date"}},"required":["company_id"],"title":"list_account_itemsArguments","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_deals":{"post":{"operationId":"list_deals","summary":"List deals (income and expense transactions) of a business office with issue date, due date, amount, unsettled amount, p","description":"List deals (income and expense transactions) of a business office with issue date, due date, amount, unsettled amount, partner and status. Filter by type, status, partner, account item and dates; page with offset. Use for \"Which unsettled freee income deals are due before 2026-12-31\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Id of the freee business office (jigyosho), taken from list_companies.","minimum":1,"title":"Company Id","type":"integer"},"type":{"anyOf":[{"enum":["income","expense"],"type":"string"},{"type":"null"}],"default":null,"description":"Income or expense deals.","title":"Type"},"status":{"anyOf":[{"enum":["unsettled","settled"],"type":"string"},{"type":"null"}],"default":null,"description":"Settlement status.","title":"Status"},"partner_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only deals of this partner id.","title":"Partner Id"},"account_item_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only deals using this account item id.","title":"Account Item Id"},"start_issue_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only deals issued on or after this date (YYYY-MM-DD).","title":"Start Issue Date"},"end_issue_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only deals issued on or before this date (YYYY-MM-DD).","title":"End Issue Date"},"start_due_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only deals due on or after this date (YYYY-MM-DD).","title":"Start Due Date"},"end_due_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only deals due on or before this date (YYYY-MM-DD).","title":"End Due Date"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of rows to skip, for paging (default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many deals to return (1 to 100).","title":"Limit"}},"required":["company_id"],"title":"list_dealsArguments","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_invoices":{"post":{"operationId":"list_invoices","summary":"List invoices of a business office with number, title, partner, issue and due dates, totals, tax, invoice status and pay","description":"List invoices of a business office with number, title, partner, issue and due dates, totals, tax, invoice status and payment status. Filter by partner, dates, status and number; page with offset. Use for \"Which freee invoices are still unpaid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Id of the freee business office (jigyosho), taken from list_companies.","minimum":1,"title":"Company Id","type":"integer"},"partner_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only invoices of this partner id.","title":"Partner Id"},"invoice_number":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only the invoice with this number.","title":"Invoice Number"},"invoice_status":{"anyOf":[{"enum":["draft","applying","remanded","rejected","approved","unsubmitted","submitted"],"type":"string"},{"type":"null"}],"default":null,"description":"Approval and submission status.","title":"Invoice Status"},"payment_status":{"anyOf":[{"enum":["unsettled","settled"],"type":"string"},{"type":"null"}],"default":null,"description":"Payment status.","title":"Payment Status"},"start_issue_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices issued on or after this date (YYYY-MM-DD).","title":"Start Issue Date"},"end_issue_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices issued on or before this date (YYYY-MM-DD).","title":"End Issue Date"},"start_due_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices due on or after this date (YYYY-MM-DD).","title":"Start Due Date"},"end_due_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices due on or before this date (YYYY-MM-DD).","title":"End Due Date"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of rows to skip, for paging (default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many invoices to return (1 to 100).","title":"Limit"}},"required":["company_id"],"title":"list_invoicesArguments","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_profit_and_loss":{"post":{"operationId":"get_profit_and_loss","summary":"Get the profit and loss statement (trial P&L) of a business office for a fiscal year or month range, with opening balanc","description":"Get the profit and loss statement (trial P&L) of a business office for a fiscal year or month range, with opening balance, debit, credit, closing balance and composition ratio per account category or item. Use for \"What was my freee profit and loss for the 2025 fiscal year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Id of the freee business office (jigyosho), taken from list_companies.","minimum":1,"title":"Company Id","type":"integer"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Fiscal year to report (the year the fiscal period starts); the current fiscal year when omitted.","title":"Fiscal Year"},"start_month":{"anyOf":[{"maximum":12,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"First month of the period (1 to 12).","title":"Start Month"},"end_month":{"anyOf":[{"maximum":12,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Last month of the period (1 to 12).","title":"End Month"},"account_item_display_type":{"anyOf":[{"enum":["account_item","group"],"type":"string"},{"type":"null"}],"default":null,"description":"Show account items or the statement display groups.","title":"Account Item Display Type"},"breakdown_display_type":{"anyOf":[{"enum":["partner","item","section","account_item","segment_1_tag","segment_2_tag","segment_3_tag"],"type":"string"},{"type":"null"}],"default":null,"description":"Break every account item down by this dimension.","title":"Breakdown Display Type"}},"required":["company_id"],"title":"get_profit_and_lossArguments","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_balance_sheet":{"post":{"operationId":"get_balance_sheet","summary":"Get the balance sheet (trial B/S) of a business office for a fiscal year or month range, with opening balance, debit, cr","description":"Get the balance sheet (trial B/S) of a business office for a fiscal year or month range, with opening balance, debit, credit and closing balance per account category or item. Use for \"What does my freee balance sheet look like at the end of fiscal 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Id of the freee business office (jigyosho), taken from list_companies.","minimum":1,"title":"Company Id","type":"integer"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Fiscal year to report (the year the fiscal period starts); the current fiscal year when omitted.","title":"Fiscal Year"},"start_month":{"anyOf":[{"maximum":12,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"First month of the period (1 to 12).","title":"Start Month"},"end_month":{"anyOf":[{"maximum":12,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Last month of the period (1 to 12).","title":"End Month"},"account_item_display_type":{"anyOf":[{"enum":["account_item","group"],"type":"string"},{"type":"null"}],"default":null,"description":"Show account items or the statement display groups.","title":"Account Item Display Type"},"breakdown_display_type":{"anyOf":[{"enum":["partner","item","section","account_item","segment_1_tag","segment_2_tag","segment_3_tag"],"type":"string"},{"type":"null"}],"default":null,"description":"Break every account item down by this dimension.","title":"Breakdown Display Type"}},"required":["company_id"],"title":"get_balance_sheetArguments","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_walletables":{"post":{"operationId":"list_walletables","summary":"List the bank accounts, credit cards and wallets registered in a business office with type, name, last synced time, sync","description":"List the bank accounts, credit cards and wallets registered in a business office with type, name, last synced time, sync status and balance. Use for \"What accounts are registered in freee and what are their balances\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Id of the freee business office (jigyosho), taken from list_companies.","minimum":1,"title":"Company Id","type":"integer"},"type":{"anyOf":[{"enum":["bank_account","credit_card","wallet"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this kind of account.","title":"Type"},"with_balance":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include balances.","title":"With Balance"},"with_last_synced_at":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include the last sync time.","title":"With Last Synced At"},"with_sync_status":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include the sync status.","title":"With Sync Status"}},"required":["company_id"],"title":"list_walletablesArguments","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_wallet_txns":{"post":{"operationId":"list_wallet_txns","summary":"List bank, card and wallet statement lines (account transactions) of a business office with date, amount, balance, direc","description":"List bank, card and wallet statement lines (account transactions) of a business office with date, amount, balance, direction, description and registration status. Filter by account, direction and dates; page with offset. Use for \"Which expense lines hit freee account 5678 in March 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Id of the freee business office (jigyosho), taken from list_companies.","minimum":1,"title":"Company Id","type":"integer"},"walletable_type":{"anyOf":[{"enum":["bank_account","credit_card","wallet"],"type":"string"},{"type":"null"}],"default":null,"description":"Kind of account (use together with walletable_id).","title":"Walletable Type"},"walletable_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only lines of this account id (from list_walletables).","title":"Walletable Id"},"entry_side":{"anyOf":[{"enum":["income","expense"],"type":"string"},{"type":"null"}],"default":null,"description":"Income or expense lines.","title":"Entry Side"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only lines on or after this date (YYYY-MM-DD).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only lines on or before this date (YYYY-MM-DD).","title":"End Date"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of rows to skip, for paging (default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many lines to return (1 to 100).","title":"Limit"}},"required":["company_id"],"title":"list_wallet_txnsArguments","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_sections":{"post":{"operationId":"list_sections","summary":"List the departments (sections) of a business office with id, name, code, parent and indent level. Use for \"Which depart","description":"List the departments (sections) of a business office with id, name, code, parent and indent level. Use for \"Which departments are defined in my freee business office\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Id of the freee business office (jigyosho), taken from list_companies.","minimum":1,"title":"Company Id","type":"integer"},"start_update_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or after this date (YYYY-MM-DD).","title":"Start Update Date"},"end_update_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only records updated on or before this date (YYYY-MM-DD).","title":"End Update Date"}},"required":["company_id"],"title":"list_sectionsArguments","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}}}}