How to Integrate Retool with Zeplin

Before connecting Zeplin's API, start with the manual reference workflow that most Retool builders use day-to-day. Open your Zeplin project in the browser (app.zeplin.io) and navigate to the Styleguide section by clicking the Styleguide tab in the left sidebar. Here you will find all the design tokens your designers have defined: Colors, Text Styles, Spacing Tokens, and Component Library entries. Click on any color swatch to see the hex code, RGB values, and the token name (e.g., 'Primary Blue — #1A73E8'). Zeplin displays the CSS-ready value underneath each token. To export the full style guide for offline reference, click the export icon (top-right of the Styleguide panel) and choose CSS or JSON export format depending on your preference. When you are building a Retool app and need to apply a specific color, open the component's Inspector panel in Retool's right sidebar, navigate to the Style section, and paste the hex code from Zeplin directly into the color input field. For typography, Zeplin's text styles show font family, weight, size, and line height — all of which map to Retool's custom text style options in the component Inspector. Going through this process once for your primary design system creates a reference sheet your whole team can use, reducing time spent context-switching between Zeplin and Retool during builds.

To access Zeplin's REST API programmatically from Retool, you need a Personal Access Token from your Zeplin account. Open Zeplin in your browser and click your profile avatar in the top-right corner, then select Profile & Settings from the dropdown menu. In the Settings page, scroll down to the Developer section or click the Developer tab in the left navigation. In the Developer section, find the Personal Access Tokens panel and click Generate New Token. Zeplin will prompt you to give the token a descriptive name — use something like 'Retool Integration' so you can identify it later. Click Generate. Zeplin displays the token value only once on screen, so copy it immediately and store it in a secure location such as a password manager or your team's secrets vault. Important: the token grants read access to all Zeplin projects that your account can access. If you need to restrict access to specific projects, consider creating a dedicated Zeplin account with only the relevant projects shared, and generate the token from that account. This follows the principle of least privilege and prevents a Retool query from accidentally exposing specs for unrelated or confidential projects. The token does not expire automatically but can be revoked at any time from the same Developer settings page — revocation takes effect immediately for all resources using that token.

With your Personal Access Token ready, navigate to the Retool Resources tab — click Resources in the top navigation bar of your Retool home page, or find it in the left sidebar depending on your Retool version. Click the blue Add Resource button in the top-right corner of the Resources list. In the resource type selector, scroll through the categories or use the search bar. Since Zeplin does not have a dedicated native connector in Retool's catalog, select REST API from the API section. The REST API resource configuration panel opens. Fill in the resource settings: - Name: enter 'Zeplin API' or 'Zeplin' for easy identification - Base URL: enter https://api.zeplin.io/v1 — this is Zeplin's current stable API base URL - Authentication: in the Headers section, click Add Header. Set the key to Authorization and the value to Bearer {{ environment.variables.ZEPLIN_PAT }} if you stored it as a configuration variable, or paste the token directly as Bearer YOUR_TOKEN_HERE (less recommended for production) Leave the other settings at defaults. In the Test Connection section, you can optionally enter a test path such as /users/me to verify authentication — a successful response returns your Zeplin user profile JSON. Click Save Changes to store the resource. Once saved, the Zeplin API resource appears in your Resources list. All queries using this resource will proxy through Retool's server-side backend, meaning your Personal Access Token is never exposed in the browser network tab — Retool handles the Authorization header injection server-side on every request.

Open or create a Retool app where you want to display Zeplin data. In the bottom Code panel, click the + New button to create a new query. Select your 'Zeplin API' resource from the Resource dropdown. The query configuration panel switches to the REST API format with fields for HTTP method, path, URL parameters, headers, and body. For your first query — fetching all projects — configure: - Method: GET - Path: /projects - URL Parameters: add 'limit' with value 100 to retrieve up to 100 projects in one call Click Run to execute the query. Zeplin returns a JSON array of project objects, each containing fields like id, name, description, created (timestamp), updated, platform (ios, android, web, osx), and thumbnail. The raw response appears in the query output panel at the bottom. Create a second query to fetch screens for a specific project: - Method: GET - Path: /projects/{{ projectsQuery.data[0].id || textInput1.value }}/screens - URL Parameters: add 'limit' with value 100 and 'offset' with value 0 for pagination This query uses the {{ }} dynamic syntax to reference either the first project ID from your projects query or a project ID entered by the user in a text input component. Drag a Table component from the Component panel onto the canvas and set its Data Source to {{ screensQuery.data }} to display the fetched screens with all their properties. Set the query Trigger mode to On page load or wire it to a Select component that lets users choose which project to inspect.

1// JavaScript transformer to reshape Zeplin screens data for a Table component
2// Add as a query transformer on the screensQuery
3const screens = data;
4return screens.map(screen => ({
5  id: screen.id,
6  name: screen.name,
7  status: screen.status || 'active',
8  updated: new Date(screen.updated * 1000).toLocaleDateString(),
9  tags: (screen.tags || []).join(', '),
10  zeplin_link: `https://app.zeplin.io/project/${screen.project_id}/screen/${screen.id}`
11}));

With Zeplin project and screen data flowing into Retool, build a practical handoff tracker that design and engineering teams can use together. This combines the Zeplin REST API data with a Retool Database table for tracking implementation status — a piece of state that Zeplin itself does not manage. First, create a Retool Database table to store tracking data. In the Retool home page, navigate to Database in the left sidebar (the table icon). Click Create new table and name it 'design_handoff'. Add columns: screen_id (Text), project_id (Text), status (Text — values: Not Started, In Progress, Built, Needs Review), notes (Text), assigned_to (Text), updated_at (Timestamp). Back in your Retool app, add a third query targeting Retool Database to read the handoff tracking data: - Resource: Retool Database - Query: SELECT * FROM design_handoff WHERE project_id = {{ projectSelect.value }} In the app canvas, arrange the layout: a Select component at the top lets users pick a Zeplin project (data from projectsQuery), a Table component in the main area shows screens from screensQuery joined with handoff status from the Retool Database query using a JavaScript transformer, and a Form component in a side panel (Container → Form) lets users update the status and notes for a selected screen row. Wire the Form's Submit button to an INSERT or UPDATE query on Retool Database that saves the implementation status. Add a success event handler that triggers the handoff query to refresh the table. For teams working at scale, add a Retool Workflow to send a Slack notification whenever a screen status changes to 'Built' — completing the loop between design and engineering. For complex multi-project tracking across many teams, RapidDev's team can help architect the full Retool solution with proper permission scoping and Workflow automation.

1// JavaScript transformer to join Zeplin screens with Retool Database tracking data
2// Run after both screensQuery and handoffQuery complete
3const screens = screensQuery.data || [];
4const tracking = handoffQuery.data || [];
5const trackingMap = {};
6tracking.forEach(row => { trackingMap[row.screen_id] = row; });
7
8return screens.map(screen => ({
9  screen_id: screen.id,
10  name: screen.name,
11  updated: new Date(screen.updated * 1000).toLocaleDateString(),
12  status: trackingMap[screen.id]?.status || 'Not Started',
13  assigned_to: trackingMap[screen.id]?.assigned_to || 'Unassigned',
14  notes: trackingMap[screen.id]?.notes || '',
15  zeplin_link: `https://app.zeplin.io/project/${screen.project_id}/screen/${screen.id}`
16}));