Connecting to Shortcut

To authenticate to Shortcut, and connect to your own data or to allow other users to connect to their data, you can use API Key authentication.

Authentication

The Shortcut API uses API Key-based authentication.

Using API Key Authentication

To authenticate using an API Key, you need to obtain your API Token from your Shortcut account settings.

You can then connect by setting the AuthScheme to APIKey and providing your API token:

AuthScheme: Set this to APIKey.
APIKey: Set this to your API token from Shortcut.

To obtain your API Token:

Log into your Shortcut account at https://app.shortcut.com/
Click on your profile icon in the lower-left corner
Select "Settings"
Navigate to "API Tokens" under your account settings
Click "Generate Token" to create a new API token
Copy your API Token

For more information, visit: https://app.shortcut.com/settings/account/api-tokens

Example connection string:

Profile=C:\profiles\Shortcut.apip;AuthScheme=APIKey;APIKey=your_api_token;

Available Tables

The Shortcut API Profile provides access to comprehensive project management and agile development data across specialized tables:

Stories - Access all story records including features, bugs, and chores with full details, workflow states, and relationships.
Epics - Query epic-level planning data with milestones, deadlines, and associated stories.
Projects - Retrieve project information, team assignments, and iteration configurations.
Iterations - Access sprint/iteration data with start/end dates, story counts, and team assignments.
Workflows - Query workflow configurations and state definitions for story progression.
Members - Access workspace member information, roles, and permissions.
Groups - Retrieve team group definitions and member assignments.
Labels - Query label definitions for categorizing and filtering stories and epics.
Milestones - Access milestone tracking with objectives, key results, and completion data.
Objectives - Query OKR objectives with key results and progress tracking.
KeyResults - Access individual key result data linked to objectives with completion tracking.
Categories - Retrieve category definitions for organizing milestones and objectives.
StoryComments - Query comments and discussions on stories with author and timestamp data.
EpicComments - Access comments and discussions on epics with full conversation history.
StoryTasks - Retrieve task checklists within stories with completion status and assignments.
StorySubTasks - Query sub-task stories that are children of parent stories.
StoryLinks - Access relationships between stories (blocks, duplicates, relates to).
StoryHistory - Query historical changes to stories with detailed audit trail data.
Files - Retrieve uploaded file attachments with metadata and download URLs.
LinkedFiles - Access external file links associated with stories and epics.
Documents - Query document pages in the knowledge base with content and organization.
Repositories - Access connected code repository configurations and integration data.
Integrations - Retrieve webhook and external integration configurations.
CustomFields - Query custom field definitions with types and available values.
EntityTemplates - Access reusable templates for stories and epics.
CurrentMember - Retrieve current authenticated user's profile and permissions.
ProjectStories - Access stories filtered by specific project with optimized performance.
IterationStories - Query stories assigned to specific iterations/sprints.
EpicStories - Retrieve all stories associated with a specific epic.
GroupStories - Access stories owned by specific team groups.
LabelStories - Query stories tagged with specific labels.
LabelEpics - Retrieve epics tagged with specific labels.
ExternalLinkStories - Access stories linked to external resources with URL filters.
MilestoneEpics - Query epics associated with specific milestones.
CategoryMilestones - Retrieve milestones organized under specific categories.
CategoryObjectives - Access objectives organized under specific categories.
EpicWorkflow - Query workflow configurations specific to epics.
EpicHealth - Access health status data for epics with velocity and risk indicators.
EpicHealthHistory - Retrieve historical health status changes for epics over time.

Usage Examples

Categories:

SELECT * FROM Categories

INSERT INTO Categories (Name, Color, ExternalId) VALUES ('Sample Name', '#FF5733', 'ext-001')

UPDATE Categories SET Name = 'Updated Name', Color = '#00FF00', IsArchived = false WHERE Id = 1

DELETE FROM Categories WHERE Id = 1

CategoryMilestones:

SELECT * FROM CategoryMilestones WHERE CategoryId = 1

CategoryObjectives:

SELECT * FROM CategoryObjectives WHERE CategoryId = 1

CurrentMember:

SELECT * FROM CurrentMember

CustomFields:

SELECT * FROM CustomFields

UPDATE CustomFields SET Name = 'Updated Field Name', Description = 'Updated description', IsEnabled = true WHERE Id = '12345678-1234-1234-1234-123456789abc'

DELETE FROM CustomFields WHERE Id = '12345678-1234-1234-1234-123456789abc'

Documents:

SELECT * FROM Documents

INSERT INTO Documents (Title, Content, ContentFormat) VALUES ('Sample Document', 'Sample description', 'markdown')

UPDATE Documents SET Title = 'Updated Title', Content = 'Updated content' WHERE Id = '12345678-1234-1234-1234-123456789abc'

DELETE FROM Documents WHERE Id = '12345678-1234-1234-1234-123456789abc'

EntityTemplates:

SELECT * FROM EntityTemplates

INSERT INTO EntityTemplates (Name, StoryContents, AuthorId) VALUES ('Sample Template', '{}', '12345678-1234-1234-1234-123456789abc')

UPDATE EntityTemplates SET Name = 'Updated Template Name' WHERE Id = '12345678-1234-1234-1234-123456789abc'

DELETE FROM EntityTemplates WHERE Id = '12345678-1234-1234-1234-123456789abc'

EpicComments:

SELECT * FROM EpicComments WHERE EpicId = 1

INSERT INTO EpicComments (EpicId, Text, AuthorId) VALUES (1, 'Sample comment text', '12345678-1234-1234-1234-123456789abc')

UPDATE EpicComments SET Text = 'Updated comment text' WHERE EpicId = 1 AND Id = 1

DELETE FROM EpicComments WHERE EpicId = 1 AND Id = 1

EpicHealth:

SELECT * FROM EpicHealth WHERE EpicId = 1

INSERT INTO EpicHealth (EpicId, Status, Text) VALUES (1, 'At Risk', 'Sample description')

EpicHealthHistory:

SELECT * FROM EpicHealthHistory WHERE EpicId = 1

Epics:

SELECT * FROM Epics

INSERT INTO Epics (Name, Description, State, Deadline) VALUES ('Sample Epic', 'Sample description', 'to do', '2024-01-15T00:00:00Z')

UPDATE Epics SET Name = 'Updated Epic', Description = 'Updated description', IsArchived = false, State = 'in progress' WHERE Id = 1

DELETE FROM Epics WHERE Id = 1

EpicStories:

SELECT * FROM EpicStories WHERE EpicId = 1

EpicWorkflow:

SELECT * FROM EpicWorkflow

ExternalLinkStories:

SELECT * FROM ExternalLinkStories WHERE ExternalLink = 'https://example.com/link'

Files:

SELECT * FROM Files

UPDATE Files SET Name = 'Updated File Name', Description = 'Updated description' WHERE Id = 1

DELETE FROM Files WHERE Id = 1

Groups:

SELECT * FROM Groups

INSERT INTO Groups (Name, MentionName, WorkflowIds, Description, Color) VALUES ('Sample Name', 'sample-group', '12345678', 'Sample description', '#FF5733')

UPDATE Groups SET Name = 'Updated Group', MentionName = 'updated-group', Description = 'Updated description', IsArchived = false WHERE Id = '12345678-1234-1234-1234-123456789abc'

GroupStories:

SELECT * FROM GroupStories WHERE GroupId = '12345678-1234-1234-1234-123456789abc'

Integrations:

SELECT * FROM Integrations WHERE Id = 1

Iterations:

SELECT * FROM Iterations

INSERT INTO Iterations (Name, StartDate, EndDate, Description) VALUES ('Sprint 1', '2024-01-15', '2024-01-29', 'Sample description')

UPDATE Iterations SET Name = 'Updated Sprint', Description = 'Updated description', StartDate = '2024-02-01', EndDate = '2024-02-15' WHERE Id = 1

DELETE FROM Iterations WHERE Id = 1

IterationStories:

SELECT * FROM IterationStories WHERE IterationId = 1

KeyResults:

SELECT * FROM KeyResults WHERE Id = '12345678-1234-1234-1234-123456789abc'

LabelEpics:

SELECT * FROM LabelEpics WHERE LabelId = 1

Labels:

SELECT * FROM Labels

INSERT INTO Labels (Name, Description, Color) VALUES ('Sample Name', 'Sample description', '#FF5733')

UPDATE Labels SET Name = 'Updated Label', Description = 'Updated description', Color = '#00FF00', IsArchived = false WHERE Id = 1

DELETE FROM Labels WHERE Id = 1

LabelStories:

SELECT * FROM LabelStories WHERE LabelId = 1

LinkedFiles:

SELECT * FROM LinkedFiles

INSERT INTO LinkedFiles (Name, Type, Url, Description) VALUES ('Sample Name', 'url', 'https://example.com', 'Sample description')

UPDATE LinkedFiles SET Name = 'Updated File', Description = 'Updated description', Url = 'https://example.com/updated' WHERE Id = 1

DELETE FROM LinkedFiles WHERE Id = 1

Members:

SELECT * FROM Members

MilestoneEpics:

SELECT * FROM MilestoneEpics WHERE MilestoneId = 1

Milestones:

SELECT * FROM Milestones

INSERT INTO Milestones (Name, Description, State) VALUES ('Sample Name', 'Sample description', 'to do')

UPDATE Milestones SET Name = 'Updated Milestone', Description = 'Updated description', State = 'in progress', IsArchived = false WHERE Id = 1

DELETE FROM Milestones WHERE Id = 1

Objectives:

SELECT * FROM Objectives

INSERT INTO Objectives (Name, Description, State) VALUES ('Sample Name', 'Sample description', 'to do')

UPDATE Objectives SET Name = 'Updated Objective', Description = 'Updated description', State = 'in progress', IsArchived = false WHERE Id = 1

DELETE FROM Objectives WHERE Id = 1

Projects:

SELECT * FROM Projects

INSERT INTO Projects (Name, TeamId, Description, Abbreviation) VALUES ('Sample Name', 1, 'Sample description', 'SP')

UPDATE Projects SET Name = 'Updated Project', Description = 'Updated description', IsArchived = false WHERE Id = 1

DELETE FROM Projects WHERE Id = 1

ProjectStories:

SELECT * FROM ProjectStories WHERE ProjectId = 1

Repositories:

SELECT * FROM Repositories

Stories:

SELECT * FROM Stories WHERE Id = 1

INSERT INTO Stories (Name, WorkflowStateId, StoryType, Description) VALUES ('New feature story', 500000028, 'feature', 'Story description here')

UPDATE Stories SET Name = 'Updated story name', Description = 'Updated description', StoryType = 'bug' WHERE Id = 1

DELETE FROM Stories WHERE Id = 1

StoryComments:

SELECT * FROM StoryComments WHERE StoryId = 1

INSERT INTO StoryComments (StoryId, Text, AuthorId) VALUES (1, 'Sample comment text', '12345678-1234-1234-1234-123456789abc')

UPDATE StoryComments SET Text = 'Updated comment text' WHERE StoryId = 1 AND Id = 1

DELETE FROM StoryComments WHERE StoryId = 1 AND Id = 1

StoryHistory:

SELECT * FROM StoryHistory WHERE StoryId = 1

StoryLinks:

SELECT * FROM StoryLinks WHERE Id = 1

INSERT INTO StoryLinks (Verb, SubjectId, ObjectId) VALUES ('blocks', 1, 2)

UPDATE StoryLinks SET Verb = 'relates to', SubjectId = 1, ObjectId = 2 WHERE Id = 1

DELETE FROM StoryLinks WHERE Id = 1

StorySubTasks:

SELECT * FROM StorySubTasks WHERE StoryId = 1

StoryTasks:

SELECT * FROM StoryTasks WHERE StoryId = 1 AND Id = 1

INSERT INTO StoryTasks (StoryId, Description, IsComplete) VALUES (1, 'Sample description', false)

UPDATE StoryTasks SET Description = 'Updated task description', IsComplete = true WHERE StoryId = 1 AND Id = 1

DELETE FROM StoryTasks WHERE StoryId = 1 AND Id = 1

Workflows:

SELECT * FROM Workflows

Connection Properties

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider.

Property	Description
APIKey	The API Token from Shortcut. You can obtain your API Token from your Shortcut account settings.
AuthScheme	The scheme used for authentication. Accepted entries are APIKey or None. Allowed values are: BASIC, NONE, NTLM, OAUTH, APIKEY, OAUTH_CLIENT, OAUTH_PASSWORD