{"openapi":"3.1.0","info":{"title":"Zuper Field Work (BYOK) API","version":"0.1.0","description":"Zuper Field Work (BYOK) lets an AI assistant read your own Zuper Field Work data through the Zuper Field Work API with a key you supply (Zuper API key). Read-only: 5 tools (list_appointments, list_recurring_jobs, list_service_tasks, list_job_folders, list_job_measurements). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-zuper-field-work.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-zuper-field-work/docs"},"termsOfService":"https://connectorbay.com/byok-zuper-field-work/terms"},"servers":[{"url":"https://byok-zuper-field-work.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-zuper-field-work/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_appointments":{"post":{"operationId":"list_appointments","summary":"List scheduled and unscheduled appointments with number, title, start and end time, trade type and the linked job (no cu","description":"List scheduled and unscheduled appointments with number, title, start and end time, trade type and the linked job (no customer or staff details). Use for \"What Zuper appointments are scheduled for next week\".","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"},"scheduled_status":{"anyOf":[{"enum":["SCHEDULED","UNSCHEDULED"],"type":"string"},{"type":"null"}],"default":null,"description":"SCHEDULED or UNSCHEDULED.","title":"Scheduled Status"},"job_uid":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only appointments linked to this job uid.","title":"Job Uid"},"from_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only appointments from this date or time.","title":"From Date"},"to_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only appointments up to this date or time.","title":"To Date"},"sort_by":{"anyOf":[{"enum":["created_at","scheduled_start_time"],"type":"string"},{"type":"null"}],"default":"created_at","description":"Sort key: created_at or scheduled_start_time.","title":"Sort By"},"sort":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"ASC or DESC.","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_appointmentsArguments","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_recurring_jobs":{"post":{"operationId":"list_recurring_jobs","summary":"List recurring job schedules with title, category, repeat frequency and interval, recurrence rule and duration (no custo","description":"List recurring job schedules with title, category, repeat frequency and interval, recurrence rule and duration (no customer details). Use for \"Which jobs repeat weekly 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"},"job_category":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Job category uid.","title":"Job Category"},"sort":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"ASC or DESC.","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_recurring_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/list_service_tasks":{"post":{"operationId":"list_service_tasks","summary":"List service tasks (work steps) with title, status, sequence, estimated duration and the job they belong to (no staff de","description":"List service tasks (work steps) with title, status, sequence, estimated duration and the job they belong to (no staff details). Use for \"Which service tasks on Zuper job 6f651e50 are 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"},"keyword":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Keyword search.","title":"Keyword"},"job_uid":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only tasks of this job uid.","title":"Job Uid"},"status":{"anyOf":[{"enum":["OPEN","IN_PROGRESS","ON_HOLD","COMPLETED","CANCELED","INCOMPLETE"],"type":"string"},{"type":"null"}],"default":null,"description":"Task status.","title":"Status"},"sort":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"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"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many tasks per page.","title":"Limit"}},"required":["dc_region"],"title":"list_service_tasksArguments","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_folders":{"post":{"operationId":"list_job_folders","summary":"List photo and file folders attached to one record (for example a job) with name, file count and sharing flag. Use for \"","description":"List photo and file folders attached to one record (for example a job) with name, file count and sharing flag. Use for \"What photo folders does Zuper job c5526bff have\".","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"},"module":{"description":"Record type that owns the folders, for example JOB.","maxLength":30,"title":"Module","type":"string"},"module_uid":{"description":"Uid of that record.","maxLength":60,"title":"Module Uid","type":"string"},"sort":{"anyOf":[{"enum":["created_at","folder_name","attachment_count"],"type":"string"},{"type":"null"}],"default":"created_at","description":"Sort key: created_at, folder_name or attachment_count.","title":"Sort"},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"ASC or DESC.","title":"Sort Order"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many folders per page.","title":"Limit"}},"required":["dc_region","module","module_uid"],"title":"list_job_foldersArguments","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_measurements":{"post":{"operationId":"list_job_measurements","summary":"List measurement orders (for example roof measurements) of one job with name, status and order and creation times. Use f","description":"List measurement orders (for example roof measurements) of one job with name, status and order and creation times. Use for \"What measurements were ordered for Zuper job 6f651e50\".","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.","maxLength":60,"title":"Job Uid","type":"string"},"sort_by":{"anyOf":[{"enum":["measurement_name","created_at","ordered_at","completed_at"],"type":"string"},{"type":"null"}],"default":"created_at","description":"Sort key: measurement_name, created_at, ordered_at or completed_at.","title":"Sort By"},"sort":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"Sort direction: DESC or ASC.","title":"Sort"}},"required":["dc_region","job_uid"],"title":"list_job_measurementsArguments","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}}}}