{"openapi":"3.1.0","info":{"title":"iugu (BYOK) API","version":"0.1.0","description":"iugu (BYOK) lets an AI assistant read your own iugu data through the iugu API with a key you supply (API token (live or test)). Read-only: 7 tools (list_invoices, get_invoice, list_customers, list_subscriptions, list_plans, get_financial_statement, list_receivables). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-iugu.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-iugu/docs"},"termsOfService":"https://connectorbay.com/byok-iugu/terms"},"servers":[{"url":"https://byok-iugu.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-iugu/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_invoices":{"post":{"operationId":"list_invoices","summary":"List invoices, newest first, with status, due date, amounts in centavos, payer, subscription, card brand and last four d","description":"List invoices, newest first, with status, due date, amounts in centavos, payer, subscription, card brand and last four digits and checkout link. Use for \"Which iugu invoices are pending and past due\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (1 to 100, default 100).","title":"Limit"},"start":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip from the start, for paging (default 0).","title":"Start"},"status_filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices in this status, for example pending, paid, canceled, partially_paid, externally_paid or refunded.","title":"Status Filter"},"customer_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices of this customer id.","title":"Customer Id"},"due_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices due on this date, YYYY-MM-DD.","title":"Due Date"},"created_at_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices created from this time. Dates use the format YYYY-MM-DDThh:mm:ss-03:00.","title":"Created At From"},"created_at_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices created until this time. Dates use the format YYYY-MM-DDThh:mm:ss-03:00.","title":"Created At To"},"paid_at_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices paid from this time. Dates use the format YYYY-MM-DDThh:mm:ss-03:00.","title":"Paid At From"},"paid_at_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices paid until this time. Dates use the format YYYY-MM-DDThh:mm:ss-03:00.","title":"Paid At To"},"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search over e-mail, name, notes and order id.","title":"Query"}},"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_invoice":{"post":{"operationId":"get_invoice","summary":"Get one invoice by id: status, due date, amounts in centavos, payer, subscription, payment method and checkout link. Use","description":"Get one invoice by id: status, due date, amounts in centavos, payer, subscription, payment method and checkout link. Use for \"Show iugu invoice EBB161AAB22849BFA047D5F1DF55AEE9\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"iugu invoice id (32 hexadecimal characters).","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_invoiceArguments","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 customers with name, e-mail, notes and creation time. Use for \"Find the iugu customer with e-mail email@iugu.com\".","description":"List customers with name, e-mail, notes and creation time. Use for \"Find the iugu customer with e-mail email@iugu.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (1 to 100, default 100).","title":"Limit"},"start":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip from the start, for paging (default 0).","title":"Start"},"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search over e-mail, name, notes and custom variables.","title":"Query"},"created_at_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only customers created from this time. Dates use the format YYYY-MM-DDThh:mm:ss-03:00.","title":"Created At From"},"created_at_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only customers created until this time. Dates use the format YYYY-MM-DDThh:mm:ss-03:00.","title":"Created At To"},"updated_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only customers updated since this time. Dates use the format YYYY-MM-DDThh:mm:ss-03:00.","title":"Updated Since"}},"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 plan, price in centavos, status, customer, billing cycle dates and cycle counts. Use for \"Which ","description":"List subscriptions with plan, price in centavos, status, customer, billing cycle dates and cycle counts. Use for \"Which iugu subscriptions are suspended\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (1 to 100, default 100).","title":"Limit"},"start":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip from the start, for paging (default 0).","title":"Start"},"status_filter":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions in this state: due, active or suspended.","title":"Status Filter"},"customer_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions of this customer id.","title":"Customer Id"},"plan_identifier":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions of the plan with this identifier.","title":"Plan Identifier"},"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search.","title":"Query"},"created_at_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions created from this time. Dates use the format YYYY-MM-DDThh:mm:ss-03:00.","title":"Created At From"},"created_at_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions created until this time. Dates use the format YYYY-MM-DDThh:mm:ss-03:00.","title":"Created At To"}},"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_plans":{"post":{"operationId":"list_plans","summary":"List subscription plans with name, identifier, interval and prices. Use for \"What subscription plans does my iugu accoun","description":"List subscription plans with name, identifier, interval and prices. Use for \"What subscription plans does my iugu account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many plans to return (1 to 1000, default 100).","title":"Limit"},"start":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip from the start, for paging (default 0).","title":"Start"},"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search.","title":"Query"}},"title":"list_plansArguments","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_financial_statement":{"post":{"operationId":"get_financial_statement","summary":"Get the account statement (credits and debits with running balance in centavos) for a year, month or day. Use for \"Show ","description":"Get the account statement (credits and debits with running balance in centavos) for a year, month or day. Use for \"Show my iugu financial statement for March 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"year":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Year, for example 2026.","title":"Year"},"month":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Month number, for example 3.","title":"Month"},"day":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Day of month, for example 15.","title":"Day"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many entries to return (default is the provider's, up to 1000; 100 recommended).","title":"Limit"},"start":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip from the start, for paging (default 0).","title":"Start"},"hl":{"anyOf":[{"enum":["en","pt-BR"],"type":"string"},{"type":"null"}],"default":null,"description":"Locale for formatted amounts.","title":"Hl"}},"title":"get_financial_statementArguments","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_receivables":{"post":{"operationId":"list_receivables","summary":"List receivables (amounts due to you) with scheduled date, status, total, taxes and your share in centavos. Use for \"Wha","description":"List receivables (amounts due to you) with scheduled date, status, total, taxes and your share in centavos. Use for \"What receivables does iugu have scheduled for me\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (1 to 100, default 100).","title":"Limit"},"start":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip from the start, for paging (default 0).","title":"Start"},"status_filter":{"anyOf":[{"enum":["pending","done","canceled"],"type":"string"},{"type":"null"}],"default":null,"description":"Only receivables with this status.","title":"Status Filter"},"since_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only receivables from this year on.","title":"Since Year"},"since_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only receivables from this month on (use with since_year).","title":"Since Month"},"to_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only receivables up to this year.","title":"To Year"},"to_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only receivables up to this month (use with to_year).","title":"To Month"}},"title":"list_receivablesArguments","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}}}}