YouTrack Import API

YouTrack lets you import content from any external source using JavaScript import scripts that map imported data to YouTrack entities. This section of the documentation describes the YouTrack import API, which you can use to create and update existing import scripts.

To learn more about working with import scripts in YouTrack, see Get Started with Import Scripts. There, you can also find a demo import script to examine and use as a base for your own script.

Working With the Import API

The YouTrack import API supports various definitions for the entities that you can import from an external source.

This API also includes the definition for a DemoClient class. This class lets you generate an interface for a client that imports entities from an external source to YouTrack.

Use the demo import script as a foundation for building your own import script without starting from scratch. If you access the demo import script in your YouTrack, you'll find the API reference and examples embedded in the script itself.

Entities and Value Types

The following entities and value types are available to custom import scripts:

Entity or value type	Description
`Article`	Represents an article entity for custom import scripts.
`Attachment`	Represents an attachment entity for custom import scripts.
`AttachmentContentWithMetadata`	Represents the content of an attachment with metadata for custom import scripts.
`AttachmentMetaData`	Represents the metadata of an attachment for custom import scripts.
`Build`	Represents a value of a custom field of build type for custom import scripts.
`Comment`	Represents a comment entity for custom import scripts.
`DateFieldValue`	Represents a value of a custom field of date type for custom import scripts.
`DateTimeFieldValue`	Represents a value of a custom field of date and time type for custom import scripts.
`DocumentFieldValue`	Represents a value for a custom field in an issue or an article for custom import scripts.
`DocumentFieldValues`	Represents field values for custom import scripts.
`DocumentFieldValuesStringPresentation`	Represents a string presentation for a custom field value in an issue or an article for custom import scripts.
`DocumentFields`	Represents predefined fields of a document that could be either issue or article for custom import scripts.
`DocumentInfo`	The base class containing information about an issue or an article for custom import scripts.
`EnumElement`	Represents a value of a custom field of enum type for custom import scripts.
`EnumerableFieldPresentation`	Represents a presentation of an enum custom field for custom import scripts.
`FieldChange`	Represents a field change entity for custom import scripts.
`FieldValue`	The ancestor for custom field value entities for custom import scripts.
`FloatFieldValue`	Represents a value of a custom field of float type for custom import scripts.
`GroupProjectField`	Represents a group project custom field entity for custom import scripts.
`HistoryItem`	Represents a change in the document history for custom import scripts.
`IntegerFieldValue`	Represents a value of a custom field of integer type for custom import scripts.
`Issue`	Represents an issue entity for custom import scripts.
`LinkType`	Represents an issue link type entity for custom import scripts.
`LinkValue`	Represents a link from one issue to another for custom import scripts.
`OwnedValue`	Represents a value of a custom field of ownedField type for custom import scripts.
`PeriodFieldValue`	Represents a value of a custom field of period type for custom import scripts.
`Project`	Represents a project entity for custom import scripts.
`ProjectField`	Represents a project custom field entity for custom import scripts.
`ProjectFieldInfo`	The base class containing information about a project custom field for custom import scripts.
`ProjectInfo`	The base class containing information about a project for custom import scripts.
`ProjectValue`	Represents the project that is set in an issue or article that belongs to this project for custom import scripts.
`Reference`	Represents a reference entity for custom import scripts.
`ServerInfo`	Represents a set of server properties for custom import scripts.
`StringFieldValue`	Represents a value of a custom field of string type for custom import scripts.
`SubItem`	The base class for authored entities that are associated with an issue for custom import scripts.
`Tag`	Represents an issue tag entity for custom import scripts.
`TextFieldValue`	Represents a value of a custom field of text type for custom import scripts.
`User`	Represents a user entity for custom import scripts.
`UserGroup`	Represents a user group entity for custom import scripts.
`Version`	Represents a value of a custom field of version type for custom import scripts.
`WorkItem`	Represents a work item entity for custom import scripts.

Client Methods

Implement these entry points and methods in your import client. For required and optional methods, see DemoClient.

Entry point or method	Description
`exports.Client(context)`	Returns the client instance that YouTrack calls during import.
`constructor(context)`	Reads import parameters, prepares credentials, and creates reusable connections.
`prepareToImport()`	Runs startup checks or caches source metadata before YouTrack starts reading entities.
`getServerInfo()`	Returns source version and time information for diagnostics and import logs.
`getProjects()`	Lists projects that can be imported from the source system.
`getProject(projectInfo)`	Returns full project data for a selected source project.
`getIssues(projectInfo, after, top)`	Returns one page of issues for a project.
`getUsers(group, skip, top)`	Returns users for a group or page of users requested by YouTrack.
`getArticles(projectInfo, after, top)`	Returns one page of articles for a project.
`getAttachmentContent(project, document, attachment)`	Returns binary content and metadata for attachments referenced by imported entities.
`getLinkTypes()`	Returns link type definitions used by imported issues.
`getTimestampFormats()`	Lists date and date-time formats that the importer can parse from source data.
`getUserTimeZoneId()`	Defines the time zone used when source timestamps do not include one.
`getIssueUpdates(projectInfo, after, updatedAfter, top)`	Returns changed issues for a project since the previous synchronization.
`getArticleUpdates(projectInfo, after, updatedAfter, top)`	Returns changed articles for a project since the previous synchronization.

10 September 2026