{"openapi":"3.1.0","info":{"title":"Numeral (BYOK) API","version":"0.1.0","description":"Numeral (BYOK) lets an AI assistant read your own Numeral data through the Numeral API with a key you supply (Numeral secret key (sk_test_... or sk_prod_...)). Read-only: 11 tools (ping_numeral, list_merchants, get_merchant, list_products, get_product, list_customers, get_customer, get_transaction, get_transaction_refunds, list_exemption_certificates, list_certificate_requests). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-numeral.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-numeral/docs"},"termsOfService":"https://connectorbay.com/byok-numeral/terms"},"servers":[{"url":"https://byok-numeral.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-numeral/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/ping_numeral":{"post":{"operationId":"ping_numeral","summary":"Check the key works: returns status, whether it is a test or production key, timestamp and API version. Use for \"Does my","description":"Check the key works: returns status, whether it is a test or production key, timestamp and API version. Use for \"Does my Numeral key work, and is it test or production\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"ping_numeralArguments","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_merchants":{"post":{"operationId":"list_merchants","summary":"List merchants (sellers) on your platform account: reference ID, name, default address and status. Use for \"List the mer","description":"List merchants (sellers) on your platform account: reference ID, name, default address and status. Use for \"List the merchants in my Numeral account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the last_merchant_id from the previous page.","title":"Cursor"}},"title":"list_merchantsArguments","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_merchant":{"post":{"operationId":"get_merchant","summary":"Get one merchant by Numeral ID or your own reference merchant ID. Use for \"Show Numeral merchant my-seller-123\".","description":"Get one merchant by Numeral ID or your own reference merchant ID. Use for \"Show Numeral merchant my-seller-123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"merchant_id":{"description":"Numeral merchant ID (merch_...) or your reference merchant ID.","maxLength":128,"title":"Merchant Id","type":"string"}},"required":["merchant_id"],"title":"get_merchantArguments","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_products":{"post":{"operationId":"list_products","summary":"List the products you registered with Numeral, with name and tax product category (up to 50 per page). Use for \"Which pr","description":"List the products you registered with Numeral, with name and tax product category (up to 50 per page). Use for \"Which products are registered in Numeral\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the last_product_id from the previous page.","title":"Cursor"}},"title":"list_productsArguments","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_product":{"post":{"operationId":"get_product","summary":"Get one product by your reference product ID: name, tax category and timestamps. Use for \"Show Numeral product p-20506\".","description":"Get one product by your reference product ID: name, tax category and timestamps. Use for \"Show Numeral product p-20506\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"reference_product_id":{"description":"Your reference product ID.","maxLength":128,"title":"Reference Product Id","type":"string"}},"required":["reference_product_id"],"title":"get_productArguments","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 known to Numeral with your reference ID and tax-exempt flag. Use for \"Which Numeral customers are tax exe","description":"List customers known to Numeral with your reference ID and tax-exempt flag. Use for \"Which Numeral customers are tax exempt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the last_customer_id from the previous page.","title":"Cursor"}},"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 Numeral customer ID: reference ID and tax-exempt flag. Use for \"Show Numeral customer cust_6126acaf\"","description":"Get one customer by Numeral customer ID: reference ID and tax-exempt flag. Use for \"Show Numeral customer cust_6126acaf\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"customer_id":{"description":"Numeral customer ID (cust_...).","maxLength":128,"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/get_transaction":{"post":{"operationId":"get_transaction","summary":"Get a recorded sale by transaction ID: order reference, currencies, line items with products and tax jurisdictions. Use ","description":"Get a recorded sale by transaction ID: order reference, currencies, line items with products and tax jurisdictions. Use for \"Show Numeral transaction tr_123456789\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"transaction_id":{"description":"Numeral transaction ID (tr_...).","maxLength":128,"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/get_transaction_refunds":{"post":{"operationId":"get_transaction_refunds","summary":"List the refunds recorded against a transaction, with processing time and refunded line items. Use for \"What refunds exi","description":"List the refunds recorded against a transaction, with processing time and refunded line items. Use for \"What refunds exist for Numeral transaction tr_123456789\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"transaction_id":{"description":"Numeral transaction ID (tr_...).","maxLength":128,"title":"Transaction Id","type":"string"}},"required":["transaction_id"],"title":"get_transaction_refundsArguments","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_exemption_certificates":{"post":{"operationId":"list_exemption_certificates","summary":"List exemption (resale) certificates with status, type, covered jurisdictions and dates. Filter by status or customer. L","description":"List exemption (resale) certificates with status, type, covered jurisdictions and dates. Filter by status or customer. Live keys only. Use for \"Which Numeral exemption certificates are expiring\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["processing","needs_info","active","expiring","expired","invalid"],"type":"string"},{"type":"null"}],"default":null,"description":"Certificate status.","title":"Status"},"customer_id":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Customer ID to filter on.","title":"Customer Id"},"id_type":{"anyOf":[{"enum":["id","reference_customer_id"],"type":"string"},{"type":"null"}],"default":"id","description":"How customer_id is matched.","title":"Id Type"},"jurisdiction":{"anyOf":[{"maxLength":16,"type":"string"},{"type":"null"}],"default":null,"description":"Jurisdiction code such as US-CA.","title":"Jurisdiction"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the next_cursor from the previous page.","title":"Cursor"}},"title":"list_exemption_certificatesArguments","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_certificate_requests":{"post":{"operationId":"list_certificate_requests","summary":"List requests sent to customers for exemption certificates, with status, customer and dates. Filter by status or custome","description":"List requests sent to customers for exemption certificates, with status, customer and dates. Filter by status or customer. Live keys only. Use for \"Which Numeral certificate requests are still pending\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["pending","fulfilled","canceled","invalid"],"type":"string"},{"type":"null"}],"default":null,"description":"Request status.","title":"Status"},"customer_id":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Customer ID to filter on.","title":"Customer Id"},"id_type":{"anyOf":[{"enum":["id","reference_customer_id"],"type":"string"},{"type":"null"}],"default":"id","description":"How customer_id is matched.","title":"Id Type"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":128,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the next_cursor from the previous page.","title":"Cursor"}},"title":"list_certificate_requestsArguments","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}}}}