{"openapi":"3.1.0","info":{"title":"Perk Travel (BYOK) API","version":"0.1.0","description":"Perk Travel (BYOK) lets an AI assistant read your own Perk Travel data through the Perk Travel API with a key you supply (Perk API key). Read-only: 7 tools (list_trips, get_trip, list_invoices, get_invoice, list_invoice_lines, list_invoice_profiles, list_cost_centers). 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...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-perk-travel.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-perk-travel/docs"},"termsOfService":"https://connectorbay.com/byok-perk-travel/terms"},"servers":[{"url":"https://byok-perk-travel.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-perk-travel/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_trips":{"post":{"operationId":"list_trips","summary":"List the company's business trips, newest modification first, with name, dates, status (booked or cancelled), start and ","description":"List the company's business trips, newest modification first, with name, dates, status (booked or cancelled), start and end location and booker id. Use for \"Which business trips were booked or changed this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["booked","cancelled"],"type":"string"},{"type":"null"}],"default":null,"description":"Trip status filter.","title":"Status"},"modified_gte":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only trips modified at or after this ISO 8601 time.","title":"Modified Gte"},"modified_lt":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only trips modified before this ISO 8601 time.","title":"Modified Lt"},"traveler_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only trips that include this Perk user id.","title":"Traveler Id"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, starting at 0, for paging.","title":"Offset"}},"title":"list_tripsArguments","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_trip":{"post":{"operationId":"get_trip","summary":"Get one trip by id with local and UTC start and end times, status, locations with coordinates and IATA code, and the boo","description":"Get one trip by id with local and UTC start and end times, status, locations with coordinates and IATA code, and the booker id. Use for \"Show the details of trip 75\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"trip_id":{"description":"Perk trip id (a number from list_trips).","minimum":1,"title":"Trip Id","type":"integer"}},"required":["trip_id"],"title":"get_tripArguments","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 issued to the company with serial number, status, dates, currency and total. Only invoices issued since 1 ","description":"List invoices issued to the company with serial number, status, dates, currency and total. Only invoices issued since 1 January 2019 are returned. Use for \"Which Perk invoices are still unpaid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["paid","unpaid"],"type":"string"},{"type":"null"}],"default":null,"description":"Invoice status filter.","title":"Status"},"billing_period":{"anyOf":[{"enum":["instant","weekly","biweekly","monthly"],"type":"string"},{"type":"null"}],"default":null,"description":"Billing period filter.","title":"Billing Period"},"issuing_date_gte":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices issued on or after this date, YYYY-MM-DD.","title":"Issuing Date Gte"},"issuing_date_lte":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices issued on or before this date, YYYY-MM-DD.","title":"Issuing Date Lte"},"sort":{"anyOf":[{"enum":["issuing_date","-issuing_date"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by issuing_date or -issuing_date (newest first).","title":"Sort"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, starting at 0, for paging.","title":"Offset"}},"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 serial number with profile, dates, billing period, currency, total, tax summary and the count of line","description":"Get one invoice by serial number with profile, dates, billing period, currency, total, tax summary and the count of lines. Bank details are not returned. Use for \"Show the totals and tax summary of invoice INV-01-987654\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"serial_number":{"description":"Invoice serial number, for example 'INV-01-987654'.","maxLength":40,"title":"Serial Number","type":"string"}},"required":["serial_number"],"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_invoice_lines":{"post":{"operationId":"list_invoice_lines","summary":"List invoice lines (individual trip expenses such as flights, hotels, trains) with date, description, amounts, service t","description":"List invoice lines (individual trip expenses such as flights, hotels, trains) with date, description, amounts, service type, trip, cost center and vendor. Traveler names and emails are left out. Use for \"What did flights cost the company in October 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["paid","unpaid"],"type":"string"},{"type":"null"}],"default":null,"description":"Invoice status filter.","title":"Status"},"billing_period":{"anyOf":[{"enum":["instant","weekly","biweekly","monthly"],"type":"string"},{"type":"null"}],"default":null,"description":"Billing period filter.","title":"Billing Period"},"issuing_date_gte":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices issued on or after this date, YYYY-MM-DD.","title":"Issuing Date Gte"},"issuing_date_lte":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices issued on or before this date, YYYY-MM-DD.","title":"Issuing Date Lte"},"serial_number_contains":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only lines on invoices whose serial number contains this text.","title":"Serial Number Contains"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, starting at 0, for paging.","title":"Offset"}},"title":"list_invoice_linesArguments","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_invoice_profiles":{"post":{"operationId":"list_invoice_profiles","summary":"List the invoice profiles (legal entities that trips are invoiced to) with name, payment method type, billing period, cu","description":"List the invoice profiles (legal entities that trips are invoiced to) with name, payment method type, billing period, currency and legal name. Use for \"Which invoice profiles does our Perk account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"exclude_personal":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to leave out personal invoice profiles.","title":"Exclude Personal"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, starting at 0, for paging.","title":"Offset"}},"title":"list_invoice_profilesArguments","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_cost_centers":{"post":{"operationId":"list_cost_centers","summary":"List the company's cost centers with id, name, cost object type and number of assigned users. Use for \"What cost centers","description":"List the company's cost centers with id, name, cost object type and number of assigned users. Use for \"What cost centers exist in our Perk account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (1 to 50).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, starting at 0, for paging.","title":"Offset"}},"title":"list_cost_centersArguments","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}}}}