{"openapi":"3.1.0","info":{"title":"airfocus (BYOK) API","version":"0.1.0","description":"airfocus (BYOK) lets an AI assistant read your own airfocus data through the airfocus API with a key you supply (API key (personal access token; EU region, US tenants use app.us.airfocus.com and are not supported)). Read-only: 8 tools (get_profile, get_team, list_workspaces, get_workspace, search_items, get_item, list_item_comments, list_status_presets). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-airfocus.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-airfocus/docs"},"termsOfService":"https://connectorbay.com/byok-airfocus/terms"},"servers":[{"url":"https://byok-airfocus.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-airfocus/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_profile":{"post":{"operationId":"get_profile","summary":"Show the airfocus user the key belongs to: name, role (admin, editor or contributor), team id and last seen time. Use fo","description":"Show the airfocus user the key belongs to: name, role (admin, editor or contributor), team id and last seen time. Use for \"Which airfocus user is my key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_profileArguments","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_team":{"post":{"operationId":"get_team","summary":"Show the airfocus team: name, slug, creation time, number of workspaces and trial end if any. Use for \"What is our airfo","description":"Show the airfocus team: name, slug, creation time, number of workspaces and trial end if any. Use for \"What is our airfocus team and how many workspaces does it have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_teamArguments","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 workspaces (roadmaps, feedback portals, product backlogs) with item type, namespace and last activity. Paged by off","description":"List workspaces (roadmaps, feedback portals, product backlogs) with item type, namespace and last activity. Paged by offset and limit. Use for \"Which workspaces do we have in airfocus\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to search archived entries instead of active ones.","title":"Archived"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"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/get_workspace":{"post":{"operationId":"get_workspace","summary":"Get one workspace by id with its name, alias, item type, status preset and last activity. Use for \"Show me airfocus work","description":"Get one workspace by id with its name, alias, item type, status preset and last activity. Use for \"Show me airfocus workspace ws_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id, taken from list_workspaces.","maxLength":200,"title":"Workspace Id","type":"string"}},"required":["workspace_id"],"title":"get_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/search_items":{"post":{"operationId":"search_items","summary":"List the items (ideas, features, feedback, bugs) of one workspace with number, name, status, assignees and dates. Paged ","description":"List the items (ideas, features, feedback, bugs) of one workspace with number, name, status, assignees and dates. Paged by offset and limit. Use for \"What items are in airfocus workspace ws_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id, taken from list_workspaces.","maxLength":200,"title":"Workspace Id","type":"string"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to search archived entries instead of active ones.","title":"Archived"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"required":["workspace_id"],"title":"search_itemsArguments","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_item":{"post":{"operationId":"get_item","summary":"Get one item by workspace id and item id, with description, status, assignees and dates. Use for \"Show me airfocus item ","description":"Get one item by workspace id and item id, with description, status, assignees and dates. Use for \"Show me airfocus item it_1 in workspace ws_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id.","maxLength":200,"title":"Workspace Id","type":"string"},"item_id":{"description":"Item id, taken from search_items.","maxLength":200,"title":"Item Id","type":"string"}},"required":["workspace_id","item_id"],"title":"get_itemArguments","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_item_comments":{"post":{"operationId":"list_item_comments","summary":"List the comments of one workspace, or only those of one item, with content blocks and times. Paged by offset and limit.","description":"List the comments of one workspace, or only those of one item, with content blocks and times. Paged by offset and limit. Use for \"What comments does airfocus item it_1 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id.","maxLength":200,"title":"Workspace Id","type":"string"},"item_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only comments of this item id; empty for the whole workspace.","title":"Item Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"required":["workspace_id"],"title":"list_item_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_status_presets":{"post":{"operationId":"list_status_presets","summary":"List the status presets (sets of workflow statuses) available to the team. Use for \"Which status presets exist in airfoc","description":"List the status presets (sets of workflow statuses) available to the team. Use for \"Which status presets exist in airfocus\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many items to skip, for paging.","title":"Offset"}},"title":"list_status_presetsArguments","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}}}}