Migrate from the Hub REST API to the YouTrack REST API

We recommend the YouTrack REST API for integrations that work with YouTrack data and access management. If your integration uses Hub REST API endpoints for this purpose, migrate these calls to the corresponding YouTrack endpoints. There is no migration deadline.

Hub remains available for standalone identity and group lookups and for Hub-specific operations. Choose the API according to your integration's purpose.

When to Migrate

Integration purpose	Recommendation
Work with YouTrack projects, project teams, or organizations	Use the YouTrack REST API. Hub endpoints do not provide this YouTrack data.
Find or manage users, groups, roles, or permissions as part of a YouTrack integration	Use the YouTrack REST API for new requests and migrate existing Hub requests.
Look up identities or groups in a standalone Hub service	Continue using Hub if it meets your integration's needs. A corresponding YouTrack endpoint does not by itself require migration.

The YouTrack REST API works with YouTrack data and applies the permissions and visibility settings configured in YouTrack. Hub and YouTrack use different permission models, and roles and permissions are not fully mirrored between them. An operation can succeed in one service and return 403 Forbidden in the other.

The Hub projects endpoint does not return YouTrack projects. Use /api/admin/projects to retrieve them. Granting additional Hub permissions cannot make YouTrack projects available through Hub.

Replacement Endpoints

The following table maps resources used by existing YouTrack integrations to their YouTrack counterparts. Check the supported operations, attributes, and permissions for each resource. Paths are relative to each API's base URL: /hub/api/rest for a built-in Hub service and /api for YouTrack. For details about the YouTrack base URL, see REST API URL and Endpoints.

Data or operation	Hub REST API endpoint or entity	YouTrack REST API replacement
Users	`/users` and `/users/{id}`	`/users` `/users/{id}`
Groups	`/usergroups` and `/usergroups/{id}`	`/groups` `/groups/{id}`
Roles	`/roles` and `/roles/{id}`	`/roles` `/roles/{id}`
Roles assigned to users or groups	`/users/{id}/projectroles` and related endpoints	`/assignedRoles`
Permissions	`/permissions`	`/permissions`
Projects	`/projects`	`/admin/projects`
Project teams	`/projects/{projectID}/team` and related endpoints	`/admin/projects/{projectID}/team` Use the `users`, `ownUsers`, and `groups` sub-resources for team membership.
Organizations	`/org` and related endpoints	`/admin/organizations`
User types	`UserType` entity	The `userType` attribute of a YouTrack user. See UserType.

For the full list of supported resources and operations, see REST API Reference.

Update Your Integration

To migrate Hub REST API calls to YouTrack:

Find the requests in your integration that call Hub REST API endpoints for YouTrack data. Include requests sent through host.fetchHub() in widget code.
Replace each request with the corresponding YouTrack REST API endpoint. For widget requests to YouTrack, use host.fetchYouTrack().
Check the authentication and permissions required by the replacement endpoint. For external integrations, use a permanent token with access to the required YouTrack service and permissions.
Update search parameters, request bodies, and requested fields to match the YouTrack resource. Hub and YouTrack use different query syntax and response formats, so changing the base URL alone is insufficient. For user and group search examples, see Users, Groups, and Access Management.
Use the id values returned by the YouTrack REST API in subsequent requests. For users and groups, use ringId, when available, to correlate the corresponding Hub entity. Projects and organizations do not have a ringId attribute. Update response handling and pagination for the YouTrack resource.
Verify the migrated operations using the account and permissions that your integration uses in production.

Migration Details

User and Group Queries

For simple user or group name searches, use query. For structured user searches by email or group membership, use searchQuery. For examples, see Search Users by Email or Group Membership. Rewrite Hub queries using the syntax supported by the YouTrack resource.

Direct and Inherited Role Scopes

The /api/assignedRoles resource accepts structured searches in the query parameter. To find roles assigned directly in a project, append ! to the project's database ID:

        curl --get 'https://example.youtrack.cloud/api/assignedRoles' \
          --data-urlencode 'query=scope: 0-1!' \
          --data-urlencode 'fields=id,role(id,name),holder(id),scope(id)' \
          --header 'Accept: application/json' \
          --header 'Authorization: Bearer <permanent_token>'
      

Replace 0-1 with the project's database ID. Without !, scope: 0-1 also includes assignments in the project's organization and the global scope. The ! suffix means an exact scope match. To negate a condition, use not. For holder filters, combined conditions, and more examples, see Access Management Query Syntax.

Group Creation and Role Assignment

Create a group with POST /api/groups, then assign its roles with separate POST /api/assignedRoles requests. Use the new group's YouTrack ID as the role holder, and specify the role and its scope. Do not include role assignments in the group creation request.

Continue Using Hub

You can continue using Hub for standalone identity and group lookups, even when a corresponding YouTrack endpoint exists. Evaluate those integrations separately from integrations that manage YouTrack data or access.

If your integration needs both services, see Match a YouTrack User with a Hub Account.

Use Hub for Hub-specific operations, such as managing Hub credentials, keys, or certificates. For supported operations, see the Hub REST API reference.

02 November 2026