Import & Export
Bring existing data into Velocity with CSV or JSON import, and export your issues and projects for backup or analysis.
Downloading your account data
Open Settings → Personal preferences → Download my data for a JSON snapshot of your signed-in account. The filename contains your account ID. The download is independent of the workspace currently open. It is also available at /api/export?entity=account&format=json with a current browser token, management CLI account sign-in or a personal account-read API key.
The versioned manifest identifies the account, export time, scope, collection counts and exclusions. All 32 documented collections are read from one database snapshot, including more than 1,000 records per collection. A failed or oversized export returns an error instead of a partial successful download. The limit is 32 MiB.
- Account profile and preferences; stored notification policy; current workspace and team memberships.
- Session/device metadata; personal and workspace API-key metadata; your OAuth consents and MCP connection metadata.
- Your received Inbox notifications, submitted feedback, referral code/credits and your own referral signup, promo redemptions, feature requests/votes and roadmap votes.
- Your authored issues, comments, documents, PRDs and PRD versions, user stories and saved views; issue assignments, subscriptions, received mentions, reactions, issue activity, upload metadata and triage feedback.
Workspace-linked collections include only your current memberships approved by the credential used for the download. Account-only CLI consent exports account records without workspace content. Departed or unapproved workspaces, other people’s account records, whole-workspace data, integration configuration, file bytes/private storage paths and internal provider/runtime/administrative logs are excluded. Refer other users’ signup records to those users.
Credential columns, passwords, token hashes and signing secrets are excluded through explicit field projections. Flexible preferences and authored content redact sensitive credential field names and recognizable token forms. The download keeps ordinary account data; it does not provide a credential backup or replace workspace exports. Exporting does not modify or delete your account. See CLI download instructions.
Importing Data
Go to Settings → Import to open the import wizard. Velocity supports CSV and JSON files, or pasted JSON. Choose a default team; rows can override it with a team UUID or identifier. Each request supports up to 100 issues and 1 MiB.
Saved outcomes and safe retries
CSV/JSON, GitHub, Linear and Jira imports have a saved job in Settings → Import. Review counts, warnings and known issue links after closing the original tab. Your jobs are private to you and current workspace administrators. Completed, partial, failed and unconfirmed results are distinct.
Import outcomes appear in your Inbox when Import activity and the main notification switch are enabled. Only the requester receives the notice. Dry runs stay in history without a notice; turning the preference back on does not send earlier outcomes.
A lost reply can be retried with the same UUID requestKey and identical input to read the existing job without importing rows again. Changed input with the same key is rejected. Starting a new operation uses a new key. Interrupted jobs are reconciled on the hourly sweep or before another import, and are never restarted automatically. Review unconfirmed rows before a new request. New GitHub operations do not yet deduplicate the same upstream issue.
Use vel imports list or vel imports get JOB_UUID in the management CLI. Job records contain counts and row references, not source files or provider credentials.
CSV Import
Upload your file
Drag and drop a .csv file onto the upload area, or click to browse. The file should have a header row with column names.
Preview columns
The wizard shows a preview of your data. Verify that columns are correctly detected. At minimum, a title column is required.
Import
Click Import Data to create issues in bulk. Keep the page open while it runs. Issues receive new identifiers in their selected teams.
Done
Review created issue links, failed rows and warnings. Use Review failed rows to correct only confirmed failures. Created issues, including those with warnings, must not be imported again. If a reply is lost or a row is uncertain, check Issues and the recorded ID before trying again.
Supported CSV columns:
| Column | Required | Description |
|---|---|---|
title | Yes | Issue title |
description | No | Plain text or a TipTap document (JSON object, or serialized JSON in CSV) |
priority | No | 0 urgent, 1 high, 2 medium, 3 low, 4 none; or URGENT, HIGH, MEDIUM, LOW, NONE. Defaults to none. |
status | No | Status name (matched against team statuses) |
assignee | No | Workspace member email; assignee_email and assigneeEmail are also accepted. Use assigneeId for a member UUID. |
labels | No | Comma-separated label names |
dueDate | No | Valid date in YYYY-MM-DD format |
teamId | If no default team | Team UUID or identifier in this workspace |
statusId, projectId, cycleId, parentId, labelIds | No | Existing workspace references; status and cycle must be in the row's team. parentId also accepts an issue identifier. |
createdAt, completedAt | No | Past ISO timestamps with timezone. Completion requires a completed status and a creation timestamp at or before completion. Backdated rows without a known completion date preserve that unknown date. |
JSON Import
Alternatively, paste JSON data directly into the import wizard. The JSON should be an array of issue objects:
[
{
"title": "Fix login bug",
"description": "Users cannot log in with SSO",
"priority": "HIGH"
},
{
"title": "Update onboarding flow",
"priority": "MEDIUM"
}
]Import from Linear
A workspace owner can open Settings → Import → Linear to migrate teams, workflow statuses, labels, projects, cycles, issues, comments, sub-issue relationships, and attachments. This is an import, not ongoing synchronization.
- Click Connect with Linear to authorize read access. OAuth credentials stay on the Velocity server. Alternatively, expand Use a personal API key instead; this key stays in memory for the import and is not saved.
- Select the Linear teams you want to import, then click Review mappings.
- Review each destination before starting. Suggested matches are editable and the importer uses the choices you review.
- Use Run dry run to check your choices without importing data, or Start import to create the imported records. Keep the tab open until progress finishes.
| Linear data | Destination choice |
|---|---|
| Team | An existing Velocity team, or a new team with a unique identifier. |
| Workflow status | A status in the destination team, or a new status with the Linear name. Changing the destination team resets these choices. |
| Label | An existing workspace label, or a new label with the Linear name. |
| Member | An existing workspace member, or leave their issues unassigned. Mapping does not invite or create user accounts. |
The review belongs to the connected Linear organization. If you change accounts or select different teams, load and review the mappings again before importing. A dry run records the import attempt but does not create imported issues or related data.
Review import results
Parent links are restored after importing the selected teams, including parents in another selected team or already imported into this workspace. Parents outside the imported data are reported for review. Existing manually chosen parents are preserved.
Repeating an import skips existing issues and can fill missing comments and parent links. It preserves the existing issues' team, status, assignee, labels, and edited text; new mapping choices apply to issues created by that import.
Files hosted on uploads.linear.app are copied into Velocity storage, subject to limits of 20 MiB per file, 50 files per issue, and 100 MiB per issue. Other safe HTTP or HTTPS attachment links stay as external links. If a file cannot be copied, its original link is preserved and the import reports a warning.
Progress reports parent links, unresolved parents, attachments, and attachment failures alongside the issue and comment counts. Read any Items to reviewbefore treating the migration as complete. If the connection ends before a completion message, inspect the imported data before retrying; an interrupted browser connection does not prove that nothing was written.
Disconnect Linear
The workspace owner can choose Disconnect Linear in the import wizard to revoke the connection and remove its stored credentials. Imported issues, comments, and files stay. If Velocity reports that revocation failed, remove its authorization in Linear's application settings too.
Exporting Data
Go to Settings → Export to download your workspace data.
Export Options
| Option | Description |
|---|---|
| Entity type | Choose what to export: Issues or Projects. |
| Format | Select CSV or JSON output format. |
| Date range | Optionally filter by creation date to export a subset of data. |
Click Export to generate and download the file. Large exports may take a few seconds to prepare. Every matching record is included, in immutable ID order, up to 32 MiB per download. Oversized exports fail before a partial file is offered; narrow the creation-date filter or use paged CLI collection commands. Edits cannot shift the paging boundary, but records remain live during an export.
Audit-log CSV/JSON downloads include all matching entries up to 5,000 rows and 32 MiB. Narrow actor, action or creation-date filters for larger results.
CSV Export Format
Exported CSV files include a header row and one row per issue or project. All fields contain the same columns as JSON downloads. Issues include title, identifier, status, priority, assignee email, description, creation date and completion date. Projects include name, status and start, target and creation dates. This is a reporting export; nested relations, labels and full account data are not included.
JSON Export Format
JSON exports produce an array of reporting objects, making them easy to process programmatically. Issue reporting exports can be imported in batches using Settings → Import after choosing a destination team; identifiers are newly allocated. Status names must match that team, and assignee emails must be workspace members. Project exports are reporting data; use typed CLI project commands to recreate them.
CLI issue import
Use vel api rest --path /api/import --method POST --input @import.json in the selected workspace. The file contains a default teamId and an issues array. The response includes per-row IDs and outcomes; incomplete results exit with code 8. Retry only corrected rows marked error. Import requests are never automatically retried.
Use exports for regular backups, data migration between workspaces, or feeding data into external reporting tools.