{"openapi":"3.1.0","info":{"title":"Orb (BYOK) API","version":"0.1.0","description":"Orb (BYOK) lets an AI assistant read your own Orb data through the Orb API with a key you supply (Orb API key). Read-only: 10 tools (list_customers, get_customer, list_subscriptions, get_subscription, list_invoices, get_invoice, list_plans, list_metrics, get_subscription_costs, list_credit_notes). The BYOK key travels with each request, is used for that one call only and is never stored, logged...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-orb.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-orb/docs"},"termsOfService":"https://connectorbay.com/byok-orb/terms"},"servers":[{"url":"https://byok-orb.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-orb/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_customers":{"post":{"operationId":"list_customers","summary":"List billing customers, newest first, with email, currency, timezone, balance and creation time. Paged by cursor. Use fo","description":"List billing customers, newest first, with email, currency, timezone, balance and creation time. Paged by cursor. Use for \"Which customers are set up in Orb\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination_metadata.next_cursor value of the previous page.","title":"Cursor"},"created_at_gte":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only customers created at or after this ISO 8601 time.","title":"Created At Gte"},"created_at_lt":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only customers created before this ISO 8601 time.","title":"Created At Lt"}},"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/get_customer":{"post":{"operationId":"get_customer","summary":"Get one customer by Orb id: contact, currency, balance, timezone and collection settings. Use for \"Show Orb customer cus","description":"Get one customer by Orb id: contact, currency, balance, timezone and collection settings. Use for \"Show Orb customer cus_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"customer_id":{"description":"Orb customer id, for example 'XuxCcCaemp9AGELm'.","maxLength":200,"title":"Customer Id","type":"string"}},"required":["customer_id"],"title":"get_customerArguments","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, newest first, with status, plan, customer, start and end dates and the current billing period. Use f","description":"List subscriptions, newest first, with status, plan, customer, start and end dates and the current billing period. Use for \"Which Orb subscriptions are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination_metadata.next_cursor value of the previous page.","title":"Cursor"},"status":{"anyOf":[{"enum":["active","ended","upcoming"],"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions in this state.","title":"Status"},"customer_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions of this Orb customer id.","title":"Customer Id"},"external_customer_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions of this external customer id.","title":"External Customer Id"},"plan_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions on this plan id.","title":"Plan Id"}},"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/get_subscription":{"post":{"operationId":"get_subscription","summary":"Get one subscription by id: status, plan, customer, dates, billing cycle day and payment terms. Use for \"Show Orb subscr","description":"Get one subscription by id: status, plan, customer, dates, billing cycle day and payment terms. Use for \"Show Orb subscription sub_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subscription_id":{"description":"Orb subscription id.","maxLength":200,"title":"Subscription Id","type":"string"}},"required":["subscription_id"],"title":"get_subscriptionArguments","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, newest issue date first, with number, status, dates, currency and totals. Filter by status, customer, sub","description":"List invoices, newest issue date first, with number, status, dates, currency and totals. Filter by status, customer, subscription or dates. Use for \"Which Orb invoices are issued but unpaid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination_metadata.next_cursor value of the previous page.","title":"Cursor"},"status":{"anyOf":[{"enum":["draft","issued","paid","synced","void"],"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices in this state.","title":"Status"},"customer_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices of this Orb customer id.","title":"Customer Id"},"external_customer_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices of this external customer id.","title":"External Customer Id"},"subscription_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices of this subscription.","title":"Subscription Id"},"invoice_date_gte":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices dated at or after this ISO 8601 time.","title":"Invoice Date Gte"},"invoice_date_lt":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices dated before this ISO 8601 time.","title":"Invoice Date Lt"}},"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: number, status, dates, currency, subtotal, total, amount due and hosted invoice link. Use for \"Sh","description":"Get one invoice by id: number, status, dates, currency, subtotal, total, amount due and hosted invoice link. Use for \"Show the details of Orb invoice inv_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"invoice_id":{"description":"Orb invoice id.","maxLength":200,"title":"Invoice Id","type":"string"}},"required":["invoice_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_plans":{"post":{"operationId":"list_plans","summary":"List pricing plans, newest first, with name, status, version, currency, net terms and trial config. Use for \"What plans ","description":"List pricing plans, newest first, with name, status, version, currency, net terms and trial config. Use for \"What plans exist in Orb\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination_metadata.next_cursor value of the previous page.","title":"Cursor"},"status":{"anyOf":[{"enum":["active","archived","draft"],"type":"string"},{"type":"null"}],"default":null,"description":"Only plans in this state.","title":"Status"}},"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/list_metrics":{"post":{"operationId":"list_metrics","summary":"List billable metrics (usage definitions) with name, description, status and the SQL that defines them. Use for \"Which u","description":"List billable metrics (usage definitions) with name, description, status and the SQL that defines them. Use for \"Which usage metrics does Orb bill on\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination_metadata.next_cursor value of the previous page.","title":"Cursor"}},"title":"list_metricsArguments","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_subscription_costs":{"post":{"operationId":"get_subscription_costs","summary":"Day-by-day costs of a subscription (subtotal and total per day) for a time window. Use for \"What has Orb subscription su","description":"Day-by-day costs of a subscription (subtotal and total per day) for a time window. Use for \"What has Orb subscription sub_1 cost per day this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subscription_id":{"description":"Orb subscription id.","maxLength":200,"title":"Subscription Id","type":"string"},"timeframe_start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"First moment included, ISO 8601 (for example 2026-10-01T00:00:00Z).","title":"Timeframe Start"},"timeframe_end":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"First moment excluded, ISO 8601.","title":"Timeframe End"},"view_mode":{"anyOf":[{"enum":["periodic","cumulative"],"type":"string"},{"type":"null"}],"default":null,"description":"periodic for each day's own cost, cumulative for running totals within the billing period.","title":"View Mode"},"currency":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Currency or custom pricing unit to show costs in.","title":"Currency"}},"required":["subscription_id"],"title":"get_subscription_costsArguments","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_credit_notes":{"post":{"operationId":"list_credit_notes","summary":"List credit notes, newest first, with number, invoice, type, totals and customer. Use for \"Which credit notes did we iss","description":"List credit notes, newest first, with number, invoice, type, totals and customer. Use for \"Which credit notes did we issue in Orb\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the pagination_metadata.next_cursor value of the previous page.","title":"Cursor"},"created_at_gte":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only credit notes created at or after this ISO 8601 time.","title":"Created At Gte"}},"title":"list_credit_notesArguments","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}}}}