Shortcut#

Shortcut is registered for CSV import, API sync, and sync-coupled user import. It imports Shortcut Stories into a reviewable import session, proposes TeamBoost user mappings from Shortcut Members or CSV actor names, and projects each Story into the internal integrations task-create draft.

Capability	Method	Status
`CSV_IMPORT`	Upload a Shortcut Story export CSV	Built
`SYNC`	Pull Stories from the Shortcut API	Built
`USER_IMPORT`	Bring Shortcut Members into task-import mapping	Built as part of API sync
`WEBHOOK`	Verify Shortcut webhook events	Not built

The endpoints below live under /api/v1/providers/shortcut/.... They are generic: the same routes serve any registered provider by substituting the {provider} path segment. Discovery requires authentication; the import and credential routes require an organization-scoped user token (see Authentication).

Discovery#

GET /api/v1/providers/shortcut

{
  "status": "success",
  "data": { "provider": "shortcut", "capabilities": ["CSV_IMPORT", "SYNC", "USER_IMPORT"] }
}

Credential Verification#

Shortcut API tokens can be stored and verified:

PUT /api/v1/providers/shortcut/credentials?organization_id=<id>
POST /api/v1/providers/shortcut/credentials/verify?organization_id=<id>

The token is treated as opaque. Verification sends the secret in the Shortcut-Token header and probes GET https://api.app.shortcut.com/api/v3/member. Stored secrets are encrypted at rest and never returned by the credential endpoints.

CSV Import#

POST /api/v1/providers/shortcut/imports/csv?organization_id=<id>

The CSV route accepts the supplied Shortcut Story export shape with these columns:

Story ID, Name, Description, Story Type, Workflow State, Estimate, Owner, Requester, Epic, Iteration, Labels, Projects, Created At, Updated At, Completed At, Started At, Due Date, Priority, Archived, Blocked, Blocker, and URL.

The parser requires Story ID, Name, Workflow State, Created At, and Updated At. It preserves all raw cells in the source record, including empty cells, and adds normalized review context for Epic, Project, Iteration, primary owner, owner count, and requester.

Semicolon-separated Owner and Labels cells are split for user mapping and labels. CSV owners and requesters are name-only in the sample export, so they are matched through sourceName rather than Shortcut member id.

Importing From the Shortcut API#

POST /api/v1/providers/shortcut/imports/sync?organization_id=<id>

Uses the stored, encrypted Shortcut token to fetch:

Members from GET /api/v3/members;
Workflows from GET /api/v3/workflows;
Groups from GET /api/v3/groups;
Epics from GET /api/v3/epics;
Iterations from GET /api/v3/iterations;
Stories from GET /api/v3/search/stories?query=is:story&page_size=250&detail=full.

The Story search follows Shortcut's next cursor until no cursor is returned. Task source records preserve raw Story fields plus workflow, state, group, epic, iteration, primary-owner, and owner-count context.

User Mapping#

Shortcut USER_IMPORT rides the sync flow. The adapter proposes mappings from:

Shortcut Members returned by GET /api/v3/members;
Story owner_ids and requested_by_id references;
actor ids referenced by Story comments and checklist task owner ids when those fields are present in the synced Story payload.

The primary matching key is the Shortcut member id (sourceAccountId). E-mail and display name are secondary matching hints.

Projection Field Coverage#

Shortcut source	TeamBoost draft field	Notes
`name`	`title`	Error if shorter than 2 characters
`story_type`	`type`	`feature` maps to `NEW_FEATURE`, `bug` maps to `BUG`, `chore` defaults to `OTHER` with a note
`description`	`description`
Story id, URL, workflow/group/epic/project/iteration refs, owner/requester refs, story links, subtasks, checklist tasks	`descriptionJson`	Preserved for review
Workflow state type/name plus Story `completed`	`status`	Backlog/unstarted -> `NOT_STARTED`; started -> `IN_PROGRESS`; done/completed -> `COMPLETED`
Story `blocked`	`status`	Not-done blocked Stories map to `BLOCKED`
Story priority	`priority`	API sync defaults to `UNKNOWN`; CSV `Priority` maps common values such as High/Medium/Low/Urgent
First `owner_ids` value or first CSV `Owner` name	`ownerId`	Resolved through user mapping; present-but-unmapped owner is a blocking `projectionError`
`requested_by_id` or CSV `Requester` name	`creatorId`, `requestedById`	Resolved through user mapping when possible; unmapped requester leaves both unset with a note
labels	`labels`	Shortcut label names pass through
Epic name	`projectTitle`
Group/Team name, or CSV `Projects` fallback	`taskGroupTitle`
`deadline`	`plannedEndDate`	Date-only deadlines normalize to end-of-day UTC
`estimate`, Iteration, parent/story links, subtasks, checklist tasks	`descriptionJson`	Preserved with mapping notes; not converted or wired into TeamBoost relationships yet

If a Story has multiple owners, the first Shortcut owner id or CSV owner name is used as the proposed TeamBoost owner and all owner identifiers are preserved in descriptionJson with a mapping note.

Operational Validation#

The adapter is covered by mocked-provider tests for Shortcut-Token auth, credential verification, search pagination, retryable failures, response validation, mapping, sync-coupled user import, registry capabilities, and task projection. CSV coverage includes required-header validation, row mapping, fixture-backed parsing, and name-only actor projection. A release smoke with a safe Shortcut workspace token and redacted API payloads is still required before announcing live API sync support.

Not Built Yet#

OAuth app install flow.
Webhook registration and Payload-Signature verification.
Standalone user-directory import before task sync.
Additional Shortcut CSV report/export variants beyond the supplied Story export profile.
Search partitioning for workspaces whose is:story query exceeds Shortcut's search-result limits.
Mapping Shortcut custom priority/severity fields into TeamBoost priority.
Automatic story-link, parent/subtask, or checklist-task wiring into TeamBoost relationships.