# Migrate from the Hub REST API to the YouTrack REST API

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/youtrack/devportal/llms.txt).

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](api-url-and-endpoints.html).

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

For the full list of supported resources and operations, see [REST API Reference](rest-api-reference.html).

## Update Your Integration

Procedure: To migrate Hub REST API calls to YouTrack:

1. Find the requests in your integration that call Hub REST API endpoints for YouTrack data. Include requests sent through [host.fetchHub()](apps-host-api.html#fetch-hub) in widget code.

2. Replace each request with the corresponding YouTrack REST API endpoint. For widget requests to YouTrack, use [host.fetchYouTrack()](apps-host-api.html#fetch-youtrack).

3. Check the authentication and permissions required by the replacement endpoint. For external integrations, use a [permanent token](Manage-Permanent-Token.html) with access to the required YouTrack service and permissions.

4. 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](api-users-yt-vs-hub.html).

5. 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](api-concept-pagination.html) for the YouTrack resource.

6. 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](api-users-yt-vs-hub.html#structured-user-searches). 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
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](api-access-management-query-syntax.html).

### 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](api-users-yt-vs-hub.html#find-youtrack-user-in-hub).

Use Hub for Hub-specific operations, such as managing Hub credentials, keys, or certificates. For supported operations, see the [Hub REST API reference](https://www.jetbrains.com/help/hub/Hub-REST-API.html).