{"openapi":"3.1.0","info":{"title":"Twist (BYOK) API","version":"0.1.0","description":"Twist (BYOK) lets an AI assistant read your own Twist data through the Twist API with a key you supply (Twist test token (from the OAuth page of your integration in the Twist App Console; has the full access of your user)). Read-only: 12 tools (get_current_user, list_workspaces, list_channels, list_threads, get_thread, list_comments, list_conversations, list_conversation_messages, get_inbox,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-twist.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-twist/docs"},"termsOfService":"https://connectorbay.com/byok-twist/terms"},"servers":[{"url":"https://byok-twist.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-twist/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 Twist user the token belongs to: id, name, short name, email, timezone, default workspace and bot flag. The tok","description":"Show the Twist user the token belongs to: id, name, short name, email, timezone, default workspace and bot flag. The token itself is never returned. Use for \"Which Twist user am I connected as\".","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_workspaces":{"post":{"operationId":"list_workspaces","summary":"List the workspaces (teams) the user belongs to with default channel, creator, creation time and plan. Use for \"Which Tw","description":"List the workspaces (teams) the user belongs to with default channel, creator, creation time and plan. Use for \"Which Twist workspaces am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_workspacesArguments","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_channels":{"post":{"operationId":"list_channels","summary":"List the channels of a workspace with name, description, privacy, archived flag and member ids. Use for \"What channels d","description":"List the channels of a workspace with name, description, privacy, archived flag and member ids. Use for \"What channels does Twist workspace 5517 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Numeric id of the workspace (see list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list only archived channels (default: active channels).","title":"Archived"}},"required":["workspace_id"],"title":"list_channelsArguments","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_threads":{"post":{"operationId":"list_threads","summary":"List threads in a channel, newest activity first by default, with title, snippet, comment count, pinned and archived fla","description":"List threads in a channel, newest activity first by default, with title, snippet, comment count, pinned and archived flags. Use for \"What are the latest threads in Twist channel 6984\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"channel_id":{"description":"Numeric id of the channel.","minimum":1,"title":"Channel Id","type":"integer"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (default 20, maximum 500).","title":"Limit"},"order_by":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by last update: desc (default) or asc.","title":"Order By"},"older_than_ts":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only threads older than this Unix time (seconds).","title":"Older Than Ts"},"is_pinned":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return only pinned threads.","title":"Is Pinned"},"is_starred":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to return only starred threads.","title":"Is Starred"}},"required":["channel_id"],"title":"list_threadsArguments","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_thread":{"post":{"operationId":"get_thread","summary":"Get one thread by id with title, content, creator, participants, comment count and timestamps. Use for \"Show Twist threa","description":"Get one thread by id with title, content, creator, participants, comment count and timestamps. Use for \"Show Twist thread 32038\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Numeric id of the thread.","minimum":1,"title":"Id","type":"integer"}},"required":["id"],"title":"get_threadArguments","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_comments":{"post":{"operationId":"list_comments","summary":"List the comments of a thread with content, author id and post time, newest first by default. Use for \"What are the late","description":"List the comments of a thread with content, author id and post time, newest first by default. Use for \"What are the latest comments on Twist thread 32038\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"thread_id":{"description":"Numeric id of the thread.","minimum":1,"title":"Thread Id","type":"integer"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (default 20, maximum 500).","title":"Limit"},"order_by":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by position in the thread: desc (default) or asc.","title":"Order By"}},"required":["thread_id"],"title":"list_commentsArguments","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 the key's user's direct and group conversations in a workspace with participants, last-message snippet and last act","description":"List the key's user's direct and group conversations in a workspace with participants, last-message snippet and last activity time. Use for \"Which Twist conversations did I have lately in workspace 5517\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Numeric id of the workspace (see list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (default 20, maximum 500).","title":"Limit"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list only archived conversations.","title":"Archived"}},"required":["workspace_id"],"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_conversation_messages":{"post":{"operationId":"list_conversation_messages","summary":"List the messages of one conversation with content, author id and post time, newest first by default. Use for \"What was ","description":"List the messages of one conversation with content, author id and post time, newest first by default. Use for \"What was said in Twist conversation 13037\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"conversation_id":{"description":"Numeric id of the conversation.","minimum":1,"title":"Conversation Id","type":"integer"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (default 20, maximum 500).","title":"Limit"},"order_by":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by position: desc (default) or asc.","title":"Order By"}},"required":["conversation_id"],"title":"list_conversation_messagesArguments","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_inbox":{"post":{"operationId":"get_inbox","summary":"List the threads in the user's inbox for a workspace, active by default. Use for \"What is in my Twist inbox for workspac","description":"List the threads in the user's inbox for a workspace, active by default. Use for \"What is in my Twist inbox for workspace 5517\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Numeric id of the workspace (see list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"How many threads to return (default 30, maximum 500).","title":"Limit"},"archive_filter":{"anyOf":[{"enum":["active","archived","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Which threads: active (default), archived or all.","title":"Archive Filter"}},"required":["workspace_id"],"title":"get_inboxArguments","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/search_workspace":{"post":{"operationId":"search_workspace","summary":"Full-text search of threads and conversations in a workspace; returns matching items with snippets and a cursor when the","description":"Full-text search of threads and conversations in a workspace; returns matching items with snippets and a cursor when there are more. Use for \"Search Twist workspace 5517 for 'launch plan'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Numeric id of the workspace (see list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"},"query":{"description":"Full-text query.","maxLength":300,"title":"Query","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (default 20, maximum 100).","title":"Limit"},"type":{"anyOf":[{"enum":["threads","messages","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Object type: threads, messages or all (default).","title":"Type"},"cursor_mark":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from a previous answer's next_cursor_mark to get the next page.","title":"Cursor Mark"}},"required":["workspace_id","query"],"title":"search_workspaceArguments","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 user groups of a workspace with member ids. Use for \"Which groups exist in Twist workspace 5517\".","description":"List the user groups of a workspace with member ids. Use for \"Which groups exist in Twist workspace 5517\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Numeric id of the workspace (see list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"}},"required":["workspace_id"],"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_unread_threads":{"post":{"operationId":"list_unread_threads","summary":"List the unread threads of the user in a workspace, with channel, thread and whether you were mentioned directly. Use fo","description":"List the unread threads of the user in a workspace, with channel, thread and whether you were mentioned directly. Use for \"Which Twist threads are unread in workspace 5517\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Numeric id of the workspace (see list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"}},"required":["workspace_id"],"title":"list_unread_threadsArguments","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}}}}