{"openapi":"3.1.0","info":{"title":"Zuplo Metering (BYOK) API","version":"0.1.0","description":"Zuplo Metering (BYOK) lets an AI assistant read your own Zuplo Metering data through the Zuplo Metering API with a key you supply (Zuplo account API key). Read-only: 9 tools (list_meters, get_meter, list_meter_group_by_values, query_meter, list_plans, get_plan, list_request_logs, list_audit_logs, get_audit_event_counts). The BYOK key travels with each request, is used for that one call only and...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-zuplo-metering.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-zuplo-metering/docs"},"termsOfService":"https://connectorbay.com/byok-zuplo-metering/terms"},"servers":[{"url":"https://byok-zuplo-metering.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-zuplo-metering/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_meters":{"post":{"operationId":"list_meters","summary":"List usage meters of a Zuplo metering bucket with event type, aggregation, value property and group-by keys. Use for \"Wh","description":"List usage meters of a Zuplo metering bucket with event type, aggregation, value property and group-by keys. Use for \"Which usage meters are defined in our Zuplo project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bucket_id":{"description":"Metering bucket id of the project (shown in the Zuplo portal under the project's Settings tab).","maxLength":100,"title":"Bucket Id","type":"string"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many items per page (1 to 1000).","title":"Page Size"},"order_by":{"anyOf":[{"enum":["key","name","aggregation","createdAt","updatedAt"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: key, name, aggregation, createdAt or updatedAt.","title":"Order By"},"order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: ASC or DESC.","title":"Order"},"include_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include deleted meters.","title":"Include Deleted"}},"required":["bucket_id"],"title":"list_metersArguments","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_meter":{"post":{"operationId":"get_meter","summary":"Get one usage meter by id or slug: aggregation, event type, value property and group-by keys. Use for \"How is the api_re","description":"Get one usage meter by id or slug: aggregation, event type, value property and group-by keys. Use for \"How is the api_requests meter aggregated in Zuplo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bucket_id":{"description":"Metering bucket id of the project (shown in the Zuplo portal under the project's Settings tab).","maxLength":100,"title":"Bucket Id","type":"string"},"meter":{"description":"Meter id or slug from list_meters, for example 'api_requests'.","maxLength":64,"title":"Meter","type":"string"}},"required":["bucket_id","meter"],"title":"get_meterArguments","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_meter_group_by_values":{"post":{"operationId":"list_meter_group_by_values","summary":"List the distinct values seen for one group-by key of a meter, optionally within a time window. Use for \"Which routes ha","description":"List the distinct values seen for one group-by key of a meter, optionally within a time window. Use for \"Which routes have been recorded on the api_requests meter\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bucket_id":{"description":"Metering bucket id of the project (shown in the Zuplo portal under the project's Settings tab).","maxLength":100,"title":"Bucket Id","type":"string"},"meter":{"description":"Meter id or slug from list_meters, for example 'api_requests'.","maxLength":64,"title":"Meter","type":"string"},"group_by_key":{"description":"Group-by key defined on the meter, for example 'route'.","maxLength":64,"title":"Group By Key","type":"string"},"from_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, RFC 3339 (inclusive), for example 2026-10-01T00:00:00Z.","title":"From Time"},"to_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, RFC 3339 (inclusive).","title":"To Time"}},"required":["bucket_id","meter","group_by_key"],"title":"list_meter_group_by_valuesArguments","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/query_meter":{"post":{"operationId":"query_meter","summary":"Query aggregated usage of a meter over a time window, optionally split into minute, hour, day or month windows and group","description":"Query aggregated usage of a meter over a time window, optionally split into minute, hour, day or month windows and grouped by one key (use 'subject' to group per consumer). Use for \"How many requests did each consumer make per day last week on the api_requests meter\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bucket_id":{"description":"Metering bucket id of the project (shown in the Zuplo portal under the project's Settings tab).","maxLength":100,"title":"Bucket Id","type":"string"},"meter":{"description":"Meter id or slug from list_meters, for example 'api_requests'.","maxLength":64,"title":"Meter","type":"string"},"from_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, RFC 3339 (inclusive), for example 2026-10-01T00:00:00Z.","title":"From Time"},"to_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, RFC 3339 (inclusive).","title":"To Time"},"window_size":{"anyOf":[{"enum":["MINUTE","HOUR","DAY","MONTH"],"type":"string"},{"type":"null"}],"default":null,"description":"Aggregation window: MINUTE, HOUR, DAY or MONTH (omit for one total over the whole period).","title":"Window Size"},"window_time_zone":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":"UTC","description":"IANA time zone for the windows, for example Europe/Berlin.","title":"Window Time Zone"},"subject":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage of this one subject (consumer).","title":"Subject"},"group_by":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"One group-by key to split the result by, or 'subject' for one row per consumer.","title":"Group By"}},"required":["bucket_id","meter"],"title":"query_meterArguments","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 monetization plans of a Zuplo metering bucket with version, status, currency and billing cadence. Use for \"Which pr","description":"List monetization plans of a Zuplo metering bucket with version, status, currency and billing cadence. Use for \"Which pricing plans have we defined in Zuplo and which are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bucket_id":{"description":"Metering bucket id of the project (shown in the Zuplo portal under the project's Settings tab).","maxLength":100,"title":"Bucket Id","type":"string"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many items per page (1 to 1000).","title":"Page Size"},"order_by":{"anyOf":[{"enum":["id","key","version","created_at","updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: id, key, version, created_at or updated_at.","title":"Order By"},"order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: ASC or DESC.","title":"Order"},"include_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include deleted plans.","title":"Include Deleted"}},"required":["bucket_id"],"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_plan":{"post":{"operationId":"get_plan","summary":"Get one monetization plan with its phases, rate cards, currency, cadence and validation errors. Use for \"What phases and","description":"Get one monetization plan with its phases, rate cards, currency, cadence and validation errors. Use for \"What phases and rate cards does the Pro plan have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bucket_id":{"description":"Metering bucket id of the project (shown in the Zuplo portal under the project's Settings tab).","maxLength":100,"title":"Bucket Id","type":"string"},"plan_id":{"description":"Plan id from list_plans.","maxLength":64,"title":"Plan Id","type":"string"}},"required":["bucket_id","plan_id"],"title":"get_planArguments","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_request_logs":{"post":{"operationId":"list_request_logs","summary":"List request log summaries of a Zuplo deployment in a time window: method, route, status, duration, country and severity","description":"List request log summaries of a Zuplo deployment in a time window: method, route, status, duration, country and severity (no bodies or client IPs). Use for \"Which requests to the orders-gateway deployment returned 5xx in the last hour\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deployment_name":{"description":"Deployment name from the Zuplo platform listing, for example 'orders-gateway-main-1a2b3c4'.","maxLength":150,"title":"Deployment Name","type":"string"},"start_time":{"description":"Start of the window, ISO 8601 (inclusive), for example 2026-10-19T08:00:00Z.","maxLength":40,"title":"Start Time","type":"string"},"end_time":{"description":"End of the window, ISO 8601 (inclusive).","maxLength":40,"title":"End Time","type":"string"},"http_status":{"anyOf":[{"enum":["2xx","3xx","4xx","5xx"],"type":"string"},{"type":"null"}],"default":null,"description":"Only requests of this status class.","title":"Http Status"},"http_method":{"anyOf":[{"enum":["GET","POST","PUT","PATCH","DELETE","HEAD","OPTIONS"],"type":"string"},{"type":"null"}],"default":null,"description":"Only requests with this HTTP method.","title":"Http Method"},"route_path":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only requests that matched this route path.","title":"Route Path"},"severity":{"anyOf":[{"enum":["debug","info","warn","error"],"type":"string"},{"type":"null"}],"default":null,"description":"Only requests whose highest log severity is this.","title":"Severity"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 200).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from pagination.cursor of the previous page.","title":"Cursor"}},"required":["deployment_name","start_time","end_time"],"title":"list_request_logsArguments","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_audit_logs":{"post":{"operationId":"list_audit_logs","summary":"List account audit log entries (action, time, success, error, resources, route) with optional filters; actor identities ","description":"List account audit log entries (action, time, success, error, resources, route) with optional filters; actor identities and client details are not returned. Use for \"Which failed actions were recorded in the Zuplo audit log this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_name":{"description":"Zuplo account name.","maxLength":100,"title":"Account Name","type":"string"},"action":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only this action, for example 'account.create'.","title":"Action"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only events after this ISO 8601 time.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only events before this ISO 8601 time.","title":"End Date"},"success":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for successful actions only, false for failed ones.","title":"Success"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip.","title":"Offset"}},"required":["account_name"],"title":"list_audit_logsArguments","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_audit_event_counts":{"post":{"operationId":"get_audit_event_counts","summary":"Count API key service audit events grouped by event type for a bucket, top groups first. Use for \"Which event types occu","description":"Count API key service audit events grouped by event type for a bucket, top groups first. Use for \"Which event types occur most often in our Zuplo key bucket audit log\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"bucket_id":{"description":"API key bucket id or name.","maxLength":100,"title":"Bucket Id","type":"string"},"group_by":{"const":"type","description":"Grouping column; only 'type' is offered here.","title":"Group By","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Maximum number of groups (1 to 100).","title":"Limit"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only events at or after this ISO 8601 time.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only events at or before this ISO 8601 time.","title":"End Date"}},"required":["bucket_id","group_by"],"title":"get_audit_event_countsArguments","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}}}}