YouTrack#

YouTrack is registered for bounded, read-only issue sync from current YouTrack Cloud with sync-coupled import of users referenced by the selected issues. Each organization supplies one permanent token, one issue query, and an explicit custom-field mapping. The adapter creates a reviewable TeamBoost import session; it does not change YouTrack or create TeamBoost tasks.

The endpoints below live under /api/v1/providers/youtrack/.... They are the generic provider endpoints and require an organization-scoped user token; see Authentication.

Discovery#

GET /api/v1/providers/youtrack

{
  "status": "success",
  "data": { "provider": "youtrack", "capabilities": ["SYNC", "USER_IMPORT"] }
}

Cloud Setup And Credential Verification#

In YouTrack, create a dedicated permanent token with permission to read every issue selected by the query. Store one strict versioned credential envelope per TeamBoost organization:

PUT /api/v1/providers/youtrack/credentials?organization_id=<id>
POST /api/v1/providers/youtrack/credentials/verify?organization_id=<id>

The write-only outer request contains a JSON-serialized secret:

{
  "secret": "{\"version\":1,\"baseUrl\":\"https://YOUR_TENANT.youtrack.cloud\",\"token\":\"YOUR_PERMANENT_TOKEN\",\"issueQuery\":\"project: DEMO #Unresolved\",\"fieldSelectors\":{\"type\":{\"name\":\"Type\",\"type\":\"SingleEnumIssueCustomField\"},\"state\":{\"name\":\"State\",\"type\":\"StateIssueCustomField\"},\"priority\":{\"name\":\"Priority\",\"type\":\"SingleEnumIssueCustomField\"},\"assignee\":{\"name\":\"Assignee\",\"type\":\"SingleUserIssueCustomField\"},\"estimation\":{\"name\":\"Estimation\",\"type\":\"PeriodIssueCustomField\"}}}"
}

The inner envelope accepts exactly version, baseUrl, token, issueQuery, and fieldSelectors:

• version must be 1.
• baseUrl must be the HTTPS service root of a *.youtrack.cloud tenant, or a legacy *.myjetbrains.com/youtrack service URL. Arbitrary/self-hosted origins, credentials in the URL, redirects, query strings, fragments, and extra paths are rejected.
• token is a non-empty permanent token and is sent only as a Bearer token.
• issueQuery is a non-empty YouTrack search query. Do not include a sort by clause; the adapter adds its fixed issue-id order for safe offset pagination.
• fieldSelectors contains exact type, state, priority, assignee, and estimation roles. The first four are required typed selector objects; estimation may be its typed object or null. The names may match the workspace's localized/custom field names, while each role's type is fixed.

Verification makes bounded read-only GET probes to /api/users/me and /api/issues using the configured query. Malformed or provider-rejected credentials return invalid_api_key; insufficient issue permission returns insufficient_permissions; rejected query/service inputs return bad_request; transient or response-contract failures return service_unavailable. Stored credentials are encrypted at rest, scoped to one TeamBoost organization, replaceable through the same PUT, and never returned by the API.

Importing Issues#

POST /api/v1/providers/youtrack/imports/sync?organization_id=<id>

The adapter performs only fixed-path GET requests. It fetches at most 50 issues per page and refuses more than 500 issues in one session. The configured query is ordered by issue id; duplicate, repeated, non-advancing, malformed, or over-limit pagination fails instead of persisting a partial import. Network, 429, and 5xx failures use at most three attempts with a total bounded wait. Redirects are never followed.

A valid empty result creates an empty reviewable session. The response preserves the requested issue object as a snake-cased source record and carries a smaller normalized task plus a proposed TeamBoost draft.

User Mapping#

USER_IMPORT rides the issue sync; there is no standalone user-import route. The adapter imports each issue Reporter, the selected Assignee, and users from other returned single- or multi-user custom fields. YouTrack User.id is the stable account key. Visible e-mail/name values are matching hints; guest, banned, or anonymized users keep only the stable id.

A mapped Assignee becomes the proposed ownerId; an assigned-but-unmapped user creates a blocking projection error. An unassigned issue keeps ownerId unset. A mapped Reporter becomes both creatorId and requestedById; otherwise both remain unset with a mapping note. The adapter never invents a reserved/system creator.

Projection Field Coverage#

Due Date is intentionally outside v1. It is not a credential selector, does not populate plannedEndDate, and is not emitted as projected dueDate context. Estimation remains context and does not become TeamBoost duration. Parent and issue links remain context and do not become task dependencies. Provider-created, updated, or resolved timestamps do not become TeamBoost scheduling fields.

Not Built Yet#

• YouTrack Server or arbitrary self-hosted base URLs.
• Due Date projection.
• CSV import.
• Standalone/full-directory user import.
• OAuth app installation.
• Webhooks, shared-token verification, replay protection, or deduplication.
• Creating or changing YouTrack issues.
• Mapping Estimation, sprints, subsystems, versions, hierarchy, or links into TeamBoost scheduling, containers, or dependencies.