{"openapi":"3.1.0","info":{"title":"KOMOJU (BYOK) API","version":"0.1.0","description":"KOMOJU (BYOK) lets an AI assistant read your own KOMOJU data through the KOMOJU API with a key you supply (secret API key). Read-only: 12 tools (list_payments, get_payment, get_session, list_customers, list_subscriptions, list_chargebacks, get_chargeback, list_events, get_balance, list_balance_transactions, list_settlements, get_settlement). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-komoju.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-komoju/docs"},"termsOfService":"https://connectorbay.com/byok-komoju/terms"},"servers":[{"url":"https://byok-komoju.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-komoju/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_payments":{"post":{"operationId":"list_payments","summary":"List payments newest first with status, amount, currency, order number and customer; filter by status, currency, your or","description":"List payments newest first with status, amount, currency, order number and customer; filter by status, currency, your order number and a time range. Card holder details are not returned. Use for \"Which KOMOJU payments were captured this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"One status or several separated by commas: pending, authorized, captured, expired, cancelled, refunded.","title":"Status"},"currency":{"anyOf":[{"maxLength":3,"type":"string"},{"type":"null"}],"default":null,"description":"Only this currency, for example JPY.","title":"Currency"},"external_order_num":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments with this order number from your own system.","title":"External Order Num"},"start_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created before this ISO 8601 time.","title":"End Time"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Objects per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_paymentsArguments","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_payment":{"post":{"operationId":"get_payment","summary":"Get one payment by id with status, amounts, refunded amount, payment method type and card brand, capture time and order ","description":"Get one payment by id with status, amounts, refunded amount, payment method type and card brand, capture time and order number. Use for \"What is the status of KOMOJU payment pay3fj6nnhvws08idzacf6et8\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"payment_id":{"description":"Payment id such as 'pay3fj6nnhvws08idzacf6et8'.","maxLength":200,"title":"Payment Id","type":"string"}},"required":["payment_id"],"title":"get_paymentArguments","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_session":{"post":{"operationId":"get_session","summary":"Get one hosted checkout session: status, amount, currency, expiry, completion time, line items and the resulting payment","description":"Get one hosted checkout session: status, amount, currency, expiry, completion time, line items and the resulting payment status. Use for \"Did KOMOJU session 4k2x9ap7qrz0m3tsgd1wbyvc6 get paid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"session_id":{"description":"Session id.","maxLength":200,"title":"Session Id","type":"string"}},"required":["session_id"],"title":"get_sessionArguments","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_customers":{"post":{"operationId":"list_customers","summary":"List saved customers (for subscriptions and one-click payments) with id, email, locale and creation time. Use for \"Which","description":"List saved customers (for subscriptions and one-click payments) with id, email, locale and creation time. Use for \"Which customers are saved in KOMOJU\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created before this ISO 8601 time.","title":"End Time"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Objects per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_customersArguments","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_subscriptions":{"post":{"operationId":"list_subscriptions","summary":"List subscriptions with status, amount, billing period and day, retry count, next charge time and start/end times. Use f","description":"List subscriptions with status, amount, billing period and day, retry count, next charge time and start/end times. Use for \"Which KOMOJU subscriptions are active and when do they renew\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created before this ISO 8601 time.","title":"End Time"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Objects per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_subscriptionsArguments","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_chargebacks":{"post":{"operationId":"list_chargebacks","summary":"List chargeback requests with amount, reason, due date and status; filter by status, payment id and due-date range. Use ","description":"List chargeback requests with amount, reason, due date and status; filter by status, payment id and due-date range. Use for \"Are there KOMOJU chargebacks I still need to answer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Chargeback status, for example pending.","title":"Status"},"payment_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only chargebacks of this payment id.","title":"Payment Id"},"due_date_start":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Due on or after this ISO 8601 time.","title":"Due Date Start"},"due_date_end":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Due on or before this ISO 8601 time.","title":"Due Date End"},"start_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created before this ISO 8601 time.","title":"End Time"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Objects per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_chargebacksArguments","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_chargeback":{"post":{"operationId":"get_chargeback","summary":"Get one chargeback request by id with payment, amount, reason, due date and status. Use for \"Show KOMOJU chargeback requ","description":"Get one chargeback request by id with payment, amount, reason, due date and status. Use for \"Show KOMOJU chargeback request cbk123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chargeback_id":{"description":"Chargeback request id (UUID) from list_chargebacks.","maxLength":200,"title":"Chargeback Id","type":"string"}},"required":["chargeback_id"],"title":"get_chargebackArguments","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_events":{"post":{"operationId":"list_events","summary":"List account events (such as payment captured or refunded) newest first with type, resource and time. Use for \"What happ","description":"List account events (such as payment captured or refunded) newest first with type, resource and time. Use for \"What happened on my KOMOJU account today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created before this ISO 8601 time.","title":"End Time"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Objects per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_eventsArguments","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":{"post":{"operationId":"get_balance","summary":"Show the balance in one currency in the smallest unit (total_balance_cents) with the breakdown of payments, refunds, cor","description":"Show the balance in one currency in the smallest unit (total_balance_cents) with the breakdown of payments, refunds, corrections and fees. Use for \"What is my KOMOJU balance in JPY\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"currency":{"description":"Three-letter currency code, for example JPY.","maxLength":3,"title":"Currency","type":"string"}},"required":["currency"],"title":"get_balanceArguments","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_balance_transactions":{"post":{"operationId":"list_balance_transactions","summary":"List balance movements in one currency with type, amount in the smallest unit and time; filter by type and time range. U","description":"List balance movements in one currency with type, amount in the smallest unit and time; filter by type and time range. Use for \"Which movements hit my KOMOJU JPY balance last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"currency":{"description":"Three-letter currency code, for example JPY.","maxLength":3,"title":"Currency","type":"string"},"type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Transaction type to keep.","title":"Type"},"start_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created before this ISO 8601 time.","title":"End Time"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Objects per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["currency"],"title":"list_balance_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/list_settlements":{"post":{"operationId":"list_settlements","summary":"List settlements with reference, status, cycle, transaction amount, fees, remittance amount and cut-off time (amounts in","description":"List settlements with reference, status, cycle, transaction amount, fees, remittance amount and cut-off time (amounts in the smallest unit). Use for \"What did KOMOJU settle to my bank this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records created before this ISO 8601 time.","title":"End Time"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Objects per page (default 20).","title":"Per Page"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_settlementsArguments","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_settlement":{"post":{"operationId":"get_settlement","summary":"Get one settlement with its breakdown: captured payments, refunds, corrections, disbursements and fees (amounts in the s","description":"Get one settlement with its breakdown: captured payments, refunds, corrections, disbursements and fees (amounts in the smallest unit). Use for \"Break down KOMOJU settlement set123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"settlement_id":{"description":"Settlement id from list_settlements.","maxLength":200,"title":"Settlement Id","type":"string"}},"required":["settlement_id"],"title":"get_settlementArguments","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}}}}