--- title: Shortcut API Integration on Truto slug: shortcut category: Ticketing canonical: "https://truto.one/integrations/detail/shortcut/" --- # Shortcut API Integration on Truto **Category:** Ticketing **Status:** Generally available ## Unified APIs ### Unified User Directory API - **Me** — - **Users** — The User object represents a User. ### Unified Ticketing API - **Attachments** — Attachments are the files associated with a ticket or a comment. - **Collections** — Tickets and contacts can be grouped into Collections. Collection resource usually maps to the various grouping systems used in the underlying product. Some examples are lists, projects, epics, etc. You can differentiate between these grouping systems using the type attribute of a Collection. - **Comments** — Comments represent the communication happening on a Ticket, both between a User and a Contact and the internal things like notes, private comments, etc. A Ticket can have one or more Comments. - **Tags** — Tags represent a common classification approach used in various ticketing systems. A Ticket may have one or more Tags associated with them. - **Teams** — Teams represent the grouping system used for Users. These are usually called groups, teams, agent groups, etc. in the underlying products. A User can belong to one or more Teams. - **Ticket Status** — Ticket Status represents the completion level of the Ticket. Some products provide customizing the Ticket Status. - **Ticket Types** — Ticket Types represent the classification system used by the underlying products for Tickets. Some examples are bugs, feature, incident, etc. - **Tickets** — Core resource which represents some work that needs to be carried out. Tickets are usually mapped to issues, tasks, work items, etc. depending on the underlying product. - **Users** — Users represent the people using the underlying ticketing system. They are usually called agents, team members, admins, etc. ### Unified Search API - **Search** — Search endpoint for all the apps. ## How it works 1. **Link your customer's Shortcut account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Shortcut.** The Proxy API is a 1-to-1 mapping of the Shortcut API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Escalate customer issues directly into engineering backlogs** — Support and helpdesk SaaS companies can let agents push critical bug reports into Shortcut as Stories with full customer context, attachments, and auto-assigned labels — keeping engineering and support in sync without manual handoffs. - **Sync delivery status back to non-engineering stakeholders** — Product, sales, or customer success platforms can pull Shortcut workflow state changes to show real-time engineering progress, so PMs and account executives never have to chase engineers for status updates. - **Auto-create tickets from monitoring and alerting systems** — Observability and APM platforms can automatically generate Shortcut Stories when incidents are detected, tag them for triage, and assign them to the right team — closing the gap between detection and developer action. - **Link product roadmap items to engineering work** — Product feedback and roadmapping tools can create Epics and Stories in Shortcut when features are prioritized, then track completion metrics to power delivery progress views inside their own product. - **Enrich Shortcut tickets with external context** — Any SaaS product can push comments, attachments, and metadata into Shortcut Stories so developers get full context — customer screenshots, error logs, deal info — without leaving their project management tool. ## What you can build - **Two-way ticket status sync** — Reflect Shortcut workflow state changes (e.g., In Progress → Completed) in your app in real time, and push status updates back when external actions occur. - **One-click bug escalation to Shortcut** — Let your users create Shortcut Bug stories directly from your UI, complete with description, attachments, tags, and team assignment — all routed through Truto's Unified Ticketing API. - **Automatic ticket routing by team** — Fetch Shortcut users and teams to build assignment rules that auto-route new Stories to the correct engineering pod based on category, priority, or customer segment. - **Bi-directional comment sync** — Push and pull comments between your app and Shortcut Stories so engineers and non-technical stakeholders can communicate without switching tools. - **Smart label tagging for traceability** — Automatically apply Shortcut labels like 'escalated-via-support' or 'auto-alert' when tickets are created through your integration, making it easy for engineering teams to filter and prioritize. - **Cross-platform ticket search** — Use the Unified Search API to let your users find and link existing Shortcut Stories from within your product, preventing duplicate tickets and surfacing related work. ## FAQs ### How does authentication work for Shortcut integrations through Truto? Shortcut uses API token-based authentication. Your end users generate a personal API token from their Shortcut settings, and Truto securely stores and manages that token so you don't have to handle credential storage or rotation yourself. ### How do Shortcut concepts map to Truto's Unified Ticketing API? Shortcut Stories map to Tickets, Workflow States map to Ticket Status, Epics/Projects map to Collections, Labels map to Tags, and Shortcut Members map to Users. Story types (bug, feature, chore) map to Ticket Types. Comments and Attachments map directly. ### Does Truto handle Shortcut API rate limits and pagination? Yes. Truto abstracts away Shortcut's rate limiting and pagination so you can query large datasets — like fetching all Stories in a workspace — without writing retry logic or cursor management code. ### Can I create tickets with specific story types (bug, feature, chore) through the Unified API? Yes. Shortcut's native story types — bug, feature, and chore — are exposed through the Ticket Types resource in Truto's Unified Ticketing API, so you can specify the type when creating a new ticket. ### What if I need a Shortcut-specific capability that isn't covered by the Unified API? Truto builds custom tools on request. If you need access to Shortcut-specific features like Iterations, Milestones, or custom fields that aren't yet in the Unified API, the Truto team can extend coverage for your use case. ### Can I look up which user is authenticated through the integration? Yes. The Unified User Directory API includes a Me resource, which returns the currently authenticated Shortcut user. This is useful for verifying connections and personalizing the integration experience.