{"openapi":"3.1.0","info":{"title":"Folk (BYOK) API","version":"0.1.0","description":"Folk (BYOK) lets an AI assistant read your own Folk data through the Folk API with a key you supply (folk API key). Read-only: 10 tools (get_current_user, list_people, get_person, list_companies, get_company, list_groups, list_deals, list_notes, list_tasks, list_users). 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-folk.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-folk/docs"},"termsOfService":"https://connectorbay.com/byok-folk/terms"},"servers":[{"url":"https://byok-folk.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-folk/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/get_current_user":{"post":{"operationId":"get_current_user","summary":"Show the folk workspace user the API key belongs to: id, full name and email. Use for \"Which folk user is my API key con","description":"Show the folk workspace user the API key belongs to: id, full name and email. Use for \"Which folk user is my API key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_current_userArguments","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_people":{"post":{"operationId":"list_people","summary":"List people (contacts) in the workspace with job title, groups, companies, emails, phones and custom field values. Optio","description":"List people (contacts) in the workspace with job title, groups, companies, emails, phones and custom field values. Optionally keep only people whose full name contains some text. Cursor-paged. Use for \"Who are the people in my folk CRM whose name contains Johnson\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name_contains":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Keep only people whose full name contains this text.","title":"Name Contains"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":512,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextLink to get the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_peopleArguments","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_person":{"post":{"operationId":"get_person","summary":"Get one person by id (starts with per_) with job title, groups, companies, emails, phones, links and custom field values","description":"Get one person by id (starts with per_) with job title, groups, companies, emails, phones, links and custom field values. Use for \"Show me the folk record for person per_1f6c1d3a-0b0e-4f4d-9a0e-1f8a6b7c9d10\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"person_id":{"description":"The person id, as returned by list_people (starts with 'per_').","maxLength":200,"title":"Person Id","type":"string"}},"required":["person_id"],"title":"get_personArguments","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_companies":{"post":{"operationId":"list_companies","summary":"List companies in the workspace with industry, employee range, groups and contact details. Optionally keep only companie","description":"List companies in the workspace with industry, employee range, groups and contact details. Optionally keep only companies whose name equals a given text. Cursor-paged. Use for \"Which companies are in my folk CRM\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name_equals":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Keep only companies whose name is exactly this text.","title":"Name Equals"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":512,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextLink to get the next page; leave empty for the first page.","title":"Cursor"}},"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/get_company":{"post":{"operationId":"get_company","summary":"Get one company by id (starts with com_) with industry, employee range, groups, contact details and custom field values.","description":"Get one company by id (starts with com_) with industry, employee range, groups, contact details and custom field values. Use for \"Show me the folk record for company com_f3855422-6740-4e6a-aa5e-449ac77047d0\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"The company id, as returned by list_companies (starts with 'com_').","maxLength":200,"title":"Company Id","type":"string"}},"required":["company_id"],"title":"get_companyArguments","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_groups":{"post":{"operationId":"list_groups","summary":"List the workspace's groups (the lists and pipelines that people, companies and deals are organised in) with id, name an","description":"List the workspace's groups (the lists and pipelines that people, companies and deals are organised in) with id, name and visibility. Use for \"What groups and pipelines exist in my folk workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":512,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextLink to get the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_groupsArguments","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_deals":{"post":{"operationId":"list_deals","summary":"List the deals (or other custom objects) of one object type in a group, with companies, people and custom field values s","description":"List the deals (or other custom objects) of one object type in a group, with companies, people and custom field values such as status. Cursor-paged. Use for \"What deals are in my Sales group in folk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"group_id":{"description":"The group id from list_groups (starts with 'grp_', 40 characters).","maxLength":200,"title":"Group Id","type":"string"},"object_type":{"description":"The object type name configured in the group, for example 'Deals'.","maxLength":200,"title":"Object Type","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":512,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextLink to get the next page; leave empty for the first page.","title":"Cursor"}},"required":["group_id","object_type"],"title":"list_dealsArguments","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_notes":{"post":{"operationId":"list_notes","summary":"List notes in the workspace with their text, the person, company or object they are attached to, author and date. Option","description":"List notes in the workspace with their text, the person, company or object they are attached to, author and date. Optionally limit to one record or search the note text. Use for \"What notes have been written about company com_f3855422-6740-4e6a-aa5e-449ac77047d0 in folk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"entity_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only notes attached to this person, company or object id (40 characters).","title":"Entity Id"},"search":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Full-text search in the note content.","title":"Search"},"created_after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only notes created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Created After"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":512,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextLink to get the next page; leave empty for the first page.","title":"Cursor"}},"title":"list_notesArguments","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 tasks in the workspace with title, due date, completion time, the record they relate to and assignees. Can be limit","description":"List tasks in the workspace with title, due date, completion time, the record they relate to and assignees. Can be limited to tasks assigned to the key's user. Use for \"Which folk tasks are assigned to me\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"only_assigned_to_me":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"'true' to list only tasks assigned to the key's user.","title":"Only Assigned To Me"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":512,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextLink to get the next page; leave empty for the first page.","title":"Cursor"}},"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_users":{"post":{"operationId":"list_users","summary":"List the users (team members) of the folk workspace with id, full name and email. Use for \"Who are the users in my folk ","description":"List the users (team members) of the folk workspace with id, full name and email. Use for \"Who are the users in my folk workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":512,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.nextLink to get the next page; leave empty for the first page.","title":"Cursor"}},"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}}}}