{"openapi":"3.1.0","info":{"title":"Planhat (BYOK) API","version":"0.1.0","description":"Planhat (BYOK) lets an AI assistant read your own Planhat data through the Planhat API with a key you supply (Planhat API access token (full access, treat as a secret)). Read-only: 9 tools (list_companies, list_end_users, list_conversations, list_licenses, list_invoices, list_tasks, list_nps_responses, list_opportunities, list_users). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-planhat.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-planhat/docs"},"termsOfService":"https://connectorbay.com/byok-planhat/terms"},"servers":[{"url":"https://byok-planhat.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-planhat/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_companies":{"post":{"operationId":"list_companies","summary":"List Planhat companies with owner, status, phase, health score, MRR, ARR, NRR, customer dates, country and tags. Use for","description":"List Planhat companies with owner, status, phase, health score, MRR, ARR, NRR, customer dates, country and tags. Use for \"Which Planhat companies have the highest ARR\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only this company id (several ids may be comma-separated).","title":"Company Id"},"limit":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (default 100, maximum 5000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip before the first one returned, for paging.","title":"Offset"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Property to sort by, for example -arr or name; prefix with - for descending order.","title":"Sort"}},"title":"list_companiesArguments","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_end_users":{"post":{"operationId":"list_end_users","summary":"List Planhat end users (customer contacts) with name, email, company, position, tags and last activity. Contains persona","description":"List Planhat end users (customer contacts) with name, email, company, position, tags and last activity. Contains personal data. Use for \"Who are the contacts at Planhat company 5f2b8a9c1d2e3f4a5b6c7d8e\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this Planhat company id (a 24-character id; several ids may be comma-separated).","title":"Company Id"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the end user with this email address.","title":"Email"},"limit":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (default 100, maximum 2000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip before the first one returned, for paging.","title":"Offset"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Property to sort by, for example -lastActive; prefix with - for descending order.","title":"Sort"}},"title":"list_end_usersArguments","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_conversations":{"post":{"operationId":"list_conversations","summary":"List logged conversations (emails, calls, meetings, notes) with type, subject, snippet, date, company, tags and assignee","description":"List logged conversations (emails, calls, meetings, notes) with type, subject, snippet, date, company, tags and assignee. Use for \"What conversations were logged for Planhat company 5f2b8a9c1d2e3f4a5b6c7d8e\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this Planhat company id (a 24-character id; several ids may be comma-separated).","title":"Company Id"},"limit":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many records to return (default 30, maximum 2000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip before the first one returned, for paging.","title":"Offset"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Property to sort by, for example -date; prefix with - for descending order.","title":"Sort"}},"title":"list_conversationsArguments","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_licenses":{"post":{"operationId":"list_licenses","summary":"List licenses (recurring revenue lines) with company, product and value. Use for \"What licenses does Planhat company 5f2","description":"List licenses (recurring revenue lines) with company, product and value. Use for \"What licenses does Planhat company 5f2b8a9c1d2e3f4a5b6c7d8e have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this Planhat company id (a 24-character id; several ids may be comma-separated).","title":"Company Id"},"limit":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (default 100, maximum 2000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip before the first one returned, for paging.","title":"Offset"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Property to sort by, for example -value; prefix with - for descending order.","title":"Sort"}},"title":"list_licensesArguments","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 recorded in Planhat with invoice number, dates, total, currency, status and company. Use for \"Which Planha","description":"List invoices recorded in Planhat with invoice number, dates, total, currency, status and company. Use for \"Which Planhat invoices are unpaid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this Planhat company id (a 24-character id; several ids may be comma-separated).","title":"Company Id"},"limit":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (default 100, maximum 2000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip before the first one returned, for paging.","title":"Offset"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Property to sort by, for example -invoiceDate; prefix with - for descending order.","title":"Sort"}},"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/list_tasks":{"post":{"operationId":"list_tasks","summary":"List Planhat tasks and events with action, description, type, start and end time, done date, owner, company and archived","description":"List Planhat tasks and events with action, description, type, start and end time, done date, owner, company and archived flag. Use for \"What open Planhat tasks do we have for this company\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this Planhat company id (a 24-character id; several ids may be comma-separated).","title":"Company Id"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include archived tasks (default false).","title":"Archived"},"limit":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (default 500, maximum 10000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip before the first one returned, for paging.","title":"Offset"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Property to sort by, for example -startTime; prefix with - for descending order.","title":"Sort"}},"title":"list_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_nps_responses":{"post":{"operationId":"list_nps_responses","summary":"List NPS survey responses with score, comment, respondent email, date and company id, for the last N days. Use for \"What","description":"List NPS survey responses with score, comment, respondent email, date and company id, for the last N days. Use for \"What NPS scores did customers give in the last 90 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this Planhat company id (a 24-character id; several ids may be comma-separated).","title":"Company Id"},"days":{"anyOf":[{"maximum":3650,"minimum":1,"type":"integer"},{"type":"null"}],"default":360,"description":"Only responses answered within this many days before today (default 360).","title":"Days"},"limit":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (default 100, maximum 10000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip before the first one returned, for paging.","title":"Offset"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Property to sort by, for example -npsDate; prefix with - for descending order.","title":"Sort"}},"title":"list_nps_responsesArguments","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_opportunities":{"post":{"operationId":"list_opportunities","summary":"List sales opportunities with title, status, sales stage, company, close and deal dates, MRR, ARR, NRR and contract leng","description":"List sales opportunities with title, status, sales stage, company, close and deal dates, MRR, ARR, NRR and contract length. Use for \"Which open opportunities does Planhat have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this Planhat company id (a 24-character id; several ids may be comma-separated).","title":"Company Id"},"limit":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (default 100, maximum 2000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip before the first one returned, for paging.","title":"Offset"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Property to sort by, for example -closeDate; prefix with - for descending order.","title":"Sort"}},"title":"list_opportunitiesArguments","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_users":{"post":{"operationId":"list_users","summary":"List Planhat workspace users (your team members) with name, email, team memberships and inactive flag. Use for \"Who are ","description":"List Planhat workspace users (your team members) with name, email, team memberships and inactive flag. Use for \"Who are the users in our Planhat workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many users to return (default and maximum 10000).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of records to skip before the first one returned, for paging.","title":"Offset"},"sort":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Property to sort by, for example lastName; prefix with - for descending order.","title":"Sort"}},"title":"list_usersArguments","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}}}}