{"openapi":"3.1.0","info":{"title":"Zuper (BYOK) API","version":"0.1.0","description":"Zuper (BYOK) lets an AI assistant read your own Zuper data through the Zuper API with a key you supply (Zuper API key). Read-only: 8 tools (list_jobs, get_job, list_job_categories, list_job_statuses, list_projects, list_customers, list_organizations, list_assets). 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 to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-zuper.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-zuper/docs"},"termsOfService":"https://connectorbay.com/byok-zuper/terms"},"servers":[{"url":"https://byok-zuper.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-zuper/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_jobs":{"post":{"operationId":"list_jobs","summary":"List jobs with title, work order number, priority, status, category, due date and timestamps. Filter by keyword, priorit","description":"List jobs with title, work order number, priority, status, category, due date and timestamps. Filter by keyword, priority, status uid or dates. Use for \"Which Zuper jobs are urgent and still open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dc_region":{"description":"Your Zuper data-centre label, the part before .zuperpro.com in your base API URL (for example us-west-1c).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Dc Region","type":"string"},"priority":{"anyOf":[{"enum":["URGENT","HIGH","MEDIUM","LOW"],"type":"string"},{"type":"null"}],"default":null,"description":"Job priority: URGENT, HIGH, MEDIUM or LOW.","title":"Priority"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword search.","title":"Keyword"},"job_status":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Job status uid (not the status name).","title":"Job Status"},"from_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs scheduled from this date.","title":"From Date"},"to_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs scheduled up to this date.","title":"To Date"},"sort_by":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"work_order_number","description":"Sort key: work_order_number, job_priority, scheduled_start_time and others.","title":"Sort By"},"sort":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"Sort direction: DESC or ASC.","title":"Sort"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"count":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 1000; keep small).","title":"Count"}},"required":["dc_region"],"title":"list_jobsArguments","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_job":{"post":{"operationId":"get_job","summary":"Get one job by uid with title, priority, status, category, due date, tags and timestamps. Use for \"Show the details of Z","description":"Get one job by uid with title, priority, status, category, due date, tags and timestamps. Use for \"Show the details of Zuper job 5f1c\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dc_region":{"description":"Your Zuper data-centre label, the part before .zuperpro.com in your base API URL (for example us-west-1c).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Dc Region","type":"string"},"job_uid":{"description":"Job uid from list_jobs.","maxLength":200,"title":"Job Uid","type":"string"}},"required":["dc_region","job_uid"],"title":"get_jobArguments","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_job_categories":{"post":{"operationId":"list_job_categories","summary":"List job categories (workflow types) with name, colour, description and estimated duration. Use for \"What job categories","description":"List job categories (workflow types) with name, colour, description and estimated duration. Use for \"What job categories exist in Zuper\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dc_region":{"description":"Your Zuper data-centre label, the part before .zuperpro.com in your base API URL (for example us-west-1c).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Dc Region","type":"string"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword search.","title":"Keyword"}},"required":["dc_region"],"title":"list_job_categoriesArguments","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_job_statuses":{"post":{"operationId":"list_job_statuses","summary":"List the statuses available for one job category, with type and colour. Use for \"What statuses can a Zuper job in catego","description":"List the statuses available for one job category, with type and colour. Use for \"What statuses can a Zuper job in category abc go through\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dc_region":{"description":"Your Zuper data-centre label, the part before .zuperpro.com in your base API URL (for example us-west-1c).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Dc Region","type":"string"},"category_uid":{"description":"Job category uid from list_job_categories.","maxLength":200,"title":"Category Uid","type":"string"}},"required":["dc_region","category_uid"],"title":"list_job_statusesArguments","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_projects":{"post":{"operationId":"list_projects","summary":"List projects with number, name, priority, status, completion percentage, planned dates and timestamps. Use for \"Which Z","description":"List projects with number, name, priority, status, completion percentage, planned dates and timestamps. Use for \"Which Zuper projects are in progress\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dc_region":{"description":"Your Zuper data-centre label, the part before .zuperpro.com in your base API URL (for example us-west-1c).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Dc Region","type":"string"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword search.","title":"Keyword"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many projects per page.","title":"Limit"},"sort":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"ASC or DESC.","title":"Sort"}},"required":["dc_region"],"title":"list_projectsArguments","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, company, tags, number of jobs and active flag (no email, phone or address). Use for \"Find the ","description":"List customers with name, company, tags, number of jobs and active flag (no email, phone or address). Use for \"Find the Zuper customer named Garcia\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dc_region":{"description":"Your Zuper data-centre label, the part before .zuperpro.com in your base API URL (for example us-west-1c).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Dc Region","type":"string"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword search.","title":"Keyword"},"sort_by":{"anyOf":[{"enum":["customer_first_name","customer_last_name","no_of_jobs","created_at"],"type":"string"},{"type":"null"}],"default":"created_at","description":"Sort key: customer_first_name, customer_last_name, no_of_jobs or created_at.","title":"Sort By"},"sort":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"Sort direction: DESC or ASC.","title":"Sort"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"count":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 1000; keep small).","title":"Count"}},"required":["dc_region"],"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_organizations":{"post":{"operationId":"list_organizations","summary":"List customer organizations with name, number of customers and creation date. Use for \"Which customer organizations exis","description":"List customer organizations with name, number of customers and creation date. Use for \"Which customer organizations exist in Zuper\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dc_region":{"description":"Your Zuper data-centre label, the part before .zuperpro.com in your base API URL (for example us-west-1c).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Dc Region","type":"string"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword search.","title":"Keyword"},"sort_by":{"anyOf":[{"enum":["organization_name","created_at"],"type":"string"},{"type":"null"}],"default":"created_at","description":"Sort key: organization_name or created_at.","title":"Sort By"},"sort":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"Sort direction: DESC or ASC.","title":"Sort"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"count":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 1000; keep small).","title":"Count"}},"required":["dc_region"],"title":"list_organizationsArguments","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_assets":{"post":{"operationId":"list_assets","summary":"List assets (equipment) with code, name, category, status, serial number, warranty date and timestamps. Use for \"Which Z","description":"List assets (equipment) with code, name, category, status, serial number, warranty date and timestamps. Use for \"Which Zuper assets are installed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dc_region":{"description":"Your Zuper data-centre label, the part before .zuperpro.com in your base API URL (for example us-west-1c).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Dc Region","type":"string"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword search.","title":"Keyword"},"asset_status":{"anyOf":[{"enum":["READY_TO_INSTALL","INSTALLED","UNDER_SERVICE","REMOVED","OBSOLETE"],"type":"string"},{"type":"null"}],"default":null,"description":"Status: READY_TO_INSTALL, INSTALLED, UNDER_SERVICE, REMOVED or OBSOLETE.","title":"Asset Status"},"sort_by":{"anyOf":[{"enum":["asset_code","asset_name","warranty_expiry_date","created_at"],"type":"string"},{"type":"null"}],"default":"created_at","description":"Sort key: asset_code, asset_name, warranty_expiry_date or created_at.","title":"Sort By"},"sort":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"Sort direction: DESC or ASC.","title":"Sort"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"count":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many records per page (1 to 1000; keep small).","title":"Count"}},"required":["dc_region"],"title":"list_assetsArguments","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}}}}