{"openapi":"3.1.0","info":{"title":"Shortcut (BYOK) API","version":"0.1.0","description":"Shortcut (BYOK) lets an AI assistant read your own Shortcut data through the Shortcut API with a key you supply (Shortcut API token). Read-only: 12 tools (get_current_member, list_members, search_stories, get_story, list_story_comments, list_epics, list_epic_stories, list_iterations, list_iteration_stories, list_workflows, list_teams, list_projects). 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-shortcut.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-shortcut/docs"},"termsOfService":"https://connectorbay.com/byok-shortcut/terms"},"servers":[{"url":"https://byok-shortcut.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-shortcut/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_member":{"post":{"operationId":"get_current_member","summary":"Show the Shortcut member the API token belongs to: name, mention name, role and workspace name. Use for \"Which Shortcut ","description":"Show the Shortcut member the API token belongs to: name, mention name, role and workspace name. Use for \"Which Shortcut member and workspace is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_current_memberArguments","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_members":{"post":{"operationId":"list_members","summary":"List the members of the Shortcut workspace with name, mention name, email address, role and disabled flag. Use for \"Who ","description":"List the members of the Shortcut workspace with name, mention name, email address, role and disabled flag. Use for \"Who are the members of my Shortcut workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to list only disabled members, false for only enabled members; leave out for all.","title":"Disabled"}},"title":"list_membersArguments","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_stories":{"post":{"operationId":"search_stories","summary":"Search Shortcut stories with Shortcut search operators (for example 'is:story owner:jane state:\"In Development\"'). Retur","description":"Search Shortcut stories with Shortcut search operators (for example 'is:story owner:jane state:\"In Development\"'). Returns story name, type, state id, epic, iteration, owners and dates, with a next-page token. Use for \"Which Shortcut stories mentioning checkout are not finished yet\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Shortcut search query; plain words or operators such as 'is:started', 'epic:\"Billing\"', 'type:bug'.","maxLength":500,"title":"Query","type":"string"},"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 250).","title":"Page Size"},"detail":{"anyOf":[{"enum":["slim","full"],"type":"string"},{"type":"null"}],"default":"slim","description":"Amount of detail per story: slim (default here) or full (includes descriptions and comments).","title":"Detail"},"next":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Next page token: the 'next' value from the previous answer. Leave out for the first page.","title":"Next"}},"required":["query"],"title":"search_storiesArguments","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_story":{"post":{"operationId":"get_story","summary":"Get one Shortcut story: description, type, state id, estimate, deadline, owners, labels, tasks and comments. Use for \"Sh","description":"Get one Shortcut story: description, type, state id, estimate, deadline, owners, labels, tasks and comments. Use for \"Show me the details of Shortcut story 123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"story_id":{"description":"Numeric story ID (the number in the story URL and in story ids, for example 123).","title":"Story Id","type":"integer"}},"required":["story_id"],"title":"get_storyArguments","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_story_comments":{"post":{"operationId":"list_story_comments","summary":"List the comments on one Shortcut story with author id, text and dates. Use for \"What comments are on Shortcut story 123","description":"List the comments on one Shortcut story with author id, text and dates. Use for \"What comments are on Shortcut story 123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"story_id":{"description":"Numeric story ID (the number in the story URL and in story ids, for example 123).","title":"Story Id","type":"integer"}},"required":["story_id"],"title":"list_story_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_epics":{"post":{"operationId":"list_epics","summary":"List Shortcut epics (all of them, without paging) with state, dates, owners and story counts. Epic IDs are used by list_","description":"List Shortcut epics (all of them, without paging) with state, dates, owners and story counts. Epic IDs are used by list_epic_stories. Use for \"What epics do we have in Shortcut and how far along are they\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"includes_description":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include each epic's description (makes answers much longer).","title":"Includes Description"}},"title":"list_epicsArguments","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_epic_stories":{"post":{"operationId":"list_epic_stories","summary":"List the stories that belong to one Shortcut epic with state, estimate, owners and dates. Use for \"Which stories are in ","description":"List the stories that belong to one Shortcut epic with state, estimate, owners and dates. Use for \"Which stories are in Shortcut epic 45\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"epic_id":{"description":"Numeric epic ID, for example 45.","title":"Epic Id","type":"integer"},"includes_description":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include each story's description (makes answers much longer).","title":"Includes Description"}},"required":["epic_id"],"title":"list_epic_storiesArguments","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_iterations":{"post":{"operationId":"list_iterations","summary":"List Shortcut iterations (sprints) with status, start and end dates and story and point counts. Use for \"What are the cu","description":"List Shortcut iterations (sprints) with status, start and end dates and story and point counts. Use for \"What are the current and upcoming Shortcut iterations\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_iterationsArguments","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_iteration_stories":{"post":{"operationId":"list_iteration_stories","summary":"List the stories in one Shortcut iteration with state, estimate, owners and dates. Use for \"What stories are planned in ","description":"List the stories in one Shortcut iteration with state, estimate, owners and dates. Use for \"What stories are planned in Shortcut iteration 7\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"iteration_id":{"description":"Numeric iteration ID, for example 7.","title":"Iteration Id","type":"integer"},"includes_description":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include each story's description (makes answers much longer).","title":"Includes Description"}},"required":["iteration_id"],"title":"list_iteration_storiesArguments","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_workflows":{"post":{"operationId":"list_workflows","summary":"List Shortcut workflows with their states (id, name, type), to turn the workflow_state_id of a story into a state name. ","description":"List Shortcut workflows with their states (id, name, type), to turn the workflow_state_id of a story into a state name. Use for \"What are the workflow states in Shortcut and what are their ids\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_workflowsArguments","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_teams":{"post":{"operationId":"list_teams","summary":"List Shortcut teams (groups) with mention name, member ids and story counts. Use for \"What teams exist in my Shortcut wo","description":"List Shortcut teams (groups) with mention name, member ids and story counts. Use for \"What teams exist in my Shortcut workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only archived teams, false for only active teams; leave out for all.","title":"Archived"}},"title":"list_teamsArguments","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_projects":{"post":{"operationId":"list_projects","summary":"List Shortcut projects (the older way of grouping stories) with abbreviation, team and story counts. Use for \"What proje","description":"List Shortcut projects (the older way of grouping stories) with abbreviation, team and story counts. Use for \"What projects does my Shortcut workspace have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_projectsArguments","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}}}}