Connector Sync API: schemas
The request and response bodies of the operations in this API.
AuthoriseSyncScheduleDto
| Property | Type | Required | Description |
|---|
connectionId | string | yes | The connection (integration) the project's binding of this adapter kind uses. authorization-api refuses it unless the project is bound to it. |
ConfirmMappingsDto
| Property | Type | Required | Description |
|---|
confirmedMappings | array of SyncMappingInputDto | yes | |
excludedResources | array of string | no | External resource IDs to exclude |
ConfirmMappingsResponseDto
| Property | Type | Required | Description |
|---|
mappingCount | number | yes | |
syncConfigId | string | no | |
ConfirmMappingsResponseDtoDataEnvelope
CreateMigrationPlanDto
| Property | Type | Required | Description |
|---|
adapterKey | SyncAdapterKey | yes | |
connectionId | string | yes | The connection whose provider the plan scans. |
direction | one of "export", "import", "merge" | no | export = internal→external, import = external→internal, merge = both directions |
mode | one of "switch_only", "migrate_and_switch", "clone_and_sync" | no | |
sourceProvider | string | yes | Source provider identifier |
targetProvider | string | yes | Target provider identifier |
CreateSyncConfigDto
| Property | Type | Required | Description |
|---|
adapterKey | one of "DOCUMENTATION", "TRACKER" | yes | Adapter kind |
conflictStrategy | one of "INTERNAL_WINS", "EXTERNAL_WINS", "NEWEST_WINS", "MANUAL" | no | Conflict resolution strategy |
direction | one of "PUSH", "PULL", "BIDIRECTIONAL" | no | Sync direction |
syncIntervalMs | number | no | Sync interval in milliseconds |
ExecuteSyncDto
| Property | Type | Required | Description |
|---|
adapterKey | one of "DOCUMENTATION", "TRACKER" | yes | Adapter kind to sync |
connectionId | string | no | The connection to sync. Defaults to the one the schedule's authority records. |
ExternalResourceDto
| Property | Type | Required | Description |
|---|
children | array of ExternalResourceDto | no | Child resources |
id | string | yes | |
metadata | object | no | Extra metadata (labels, version, etc.) |
path | string | no | Hierarchical path |
title | string | yes | |
type | string | yes | Resource type |
ExternalResourceDtoDataArrayEnvelope
GenerateMappingDto
MappingProjectContextDto
| Property | Type | Required | Description |
|---|
description | string | no | |
name | string | no | |
tags | array of string | no | |
MigrationDecisionDto
| Property | Type | Required | Description |
|---|
deepLink | string or null | yes | Deep link to the ask in the Decisions queue, or null. |
id | string | yes | Decision id. |
outcome | string or null | yes | Settled outcome, or null while the ask is still answerable. |
settledOptionKey | string or null | yes | The option key that settled it, or null. |
status | string | yes | The decision's lifecycle state, in decision-api's vocabulary. |
title | string | yes | Human-readable title of the ask. |
MigrationJobDetailDto
| Property | Type | Required | Description |
|---|
adapterKey | SyncAdapterKey | yes | |
completedAt | string or null | yes | When execution finished, ISO-8601, or null. |
createdAt | string | yes | When the plan was created, ISO-8601. |
createdBy | string | yes | Actor that planned the migration. |
decisionId | string or null | yes | The decision that gates this job, or null before the ask has been opened. Always PRESENT — null is the value, not an absence. |
direction | string | yes | One of export | import | merge. export is internal→external, import external→internal, merge both. Typed as a string for the same reason as mode. |
errorLog | object or null | yes | Why the job FAILED, or null. Present on the summary because it is the reason a status is FAILED and it is bounded. |
failedItems | number | yes | |
id | string | yes | Migration job id. |
migratedItems | number | yes | |
mode | string | yes | One of switch_only | migrate_and_switch | clone_and_sync. Typed as a string because the column is an open String, not a Prisma enum — see the note at the top of this file. |
orgId | string | yes | |
planJson | object or null | yes | Preview of what the plan scan found: { totalItems, items[] }, each item an identity { id, type } only; titles stay in the source system. Shaped by the SOURCE system, so it is published as an open object rather than a typed one. Null before a scan has run. |
projectId | string | yes | |
sourceProvider | string | yes | Source provider identifier. |
startedAt | string or null | yes | When execution began, ISO-8601, or null. |
status | MigrationJobStatus | yes | |
targetProvider | string | yes | Target provider identifier. |
totalItems | number | yes | Items the plan scan found. |
MigrationJobDetailDtoDataEnvelope
MigrationJobResponseDto
| Property | Type | Required | Description |
|---|
adapterKey | SyncAdapterKey | yes | |
completedAt | string or null | yes | When execution finished, ISO-8601, or null. |
createdAt | string | yes | When the plan was created, ISO-8601. |
createdBy | string | yes | Actor that planned the migration. |
decisionId | string or null | yes | The decision that gates this job, or null before the ask has been opened. Always PRESENT — null is the value, not an absence. |
direction | string | yes | One of export | import | merge. export is internal→external, import external→internal, merge both. Typed as a string for the same reason as mode. |
errorLog | object or null | yes | Why the job FAILED, or null. Present on the summary because it is the reason a status is FAILED and it is bounded. |
failedItems | number | yes | |
id | string | yes | Migration job id. |
migratedItems | number | yes | |
mode | string | yes | One of switch_only | migrate_and_switch | clone_and_sync. Typed as a string because the column is an open String, not a Prisma enum — see the note at the top of this file. |
orgId | string | yes | |
projectId | string | yes | |
sourceProvider | string | yes | Source provider identifier. |
startedAt | string or null | yes | When execution began, ISO-8601, or null. |
status | MigrationJobStatus | yes | |
targetProvider | string | yes | Target provider identifier. |
totalItems | number | yes | Items the plan scan found. |
MigrationJobResponseDtoDataArrayEnvelope
MigrationJobStatus
Type: one of "PLANNING", "PENDING_CONFIRMATION", "CONFIRMED", "RUNNING", "COMPLETED", "FAILED", "CANCELLED"
MigrationStatusDto
| Property | Type | Required | Description |
|---|
completedAt | string or null | yes | When execution finished, ISO-8601, or null. |
decision | MigrationDecisionDto or null | yes | The ask, surfaced where its RAISER can see it. PENDING_CONFIRMATION on its own tells an operator that something is waiting and nothing about what — and the person most likely to be watching is barred from answering (selfAnswerAllowed: false) and is therefore filtered out of the decisions queue. Null when no ask has been opened, or when decision-api has no record for this job. |
failedItems | number | yes | |
id | string | yes | Migration job id. |
migratedItems | number | yes | |
progress | number | yes | Percent of totalItems migrated, rounded. 0 when the plan is empty. |
startedAt | string or null | yes | When execution began, ISO-8601, or null. |
status | MigrationJobStatus | yes | |
totalItems | number | yes | |
MigrationStatusDtoDataEnvelope
ProblemActionableBy
Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.
Type: one of "user", "org-admin", "platform", "none"
ProblemDetailsDto
RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.
| Property | Type | Required | Description |
|---|
actionableBy | ProblemActionableBy | no | Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed. |
code | string | yes | SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name. |
detail | string | no | Human-readable and specific to THIS occurrence. |
errors | array of ProblemFieldIssueDto | no | Field-level issues, when the refusal is about the request body. |
instance | string | no | URI reference identifying the occurrence — a request path, a run, a row. |
params | map of string or number or boolean | no | Safe i18n interpolation values for the message keyed by code — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics. |
retry | ProblemRetry | no | What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known. |
status | number | yes | The HTTP status code, repeated in the body so a logged document is self-contained. |
title | string | yes | Short, human-readable, and STABLE for a given type. Never per-occurrence — that is detail. |
traceId | string | no | W3C trace-context trace-id, present when the caller sent a traceparent. Omitted rather than invented when it did not. |
type | string | yes | Absolute URI identifying the refusal TYPE. Derived one-to-one from code, so a caller may branch on either and can never be told two different things. Never about:blank. |
ProblemFieldIssueDto
| Property | Type | Required | Description |
|---|
code | string | no | SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem. |
detail | string | yes | Prose for logs and developers. A frontend localises from code + params instead. |
params | map of string or number or boolean | no | Safe i18n interpolation values for this issue's code. |
pointer | string | yes | RFC 6901 JSON Pointer into the request body. Root is "/". |
ProblemRetry
What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.
Type: one of "transient", "after-change", "never"
SyncAdapterKey
Type: one of "DOCUMENTATION", "TRACKER"
SyncAnalysisResponseDto
| Property | Type | Required | Description |
|---|
adapterKey | string | yes | |
ambiguities | array of object or null | no | Resources that could not be auto-mapped |
connectionId | string | yes | |
createdAt | string | yes | |
errorCode | string or null | no | |
errorMessage | string or null | no | |
id | string | yes | |
mappingProposal | array of object or null | no | Proposed internal ↔ external mapping |
orgId | string | yes | |
projectId | string | yes | |
status | one of "SCANNING", "COMPLETED", "FAILED" | yes | |
updatedAt | string | yes | |
SyncAnalysisResponseDtoDataArrayEnvelope
SyncAnalysisResponseDtoDataEnvelope
SyncAuthorityDto
| Property | Type | Required | Description |
|---|
connectionId | string or null | no | The connection the authority is for. |
ownerId | string or null | no | |
ownerKind | one of "USER", "ORG" or null | no | |
state | one of "not_required", "required", "unprovisioned", "held", "ended" | yes | |
statusLine | string or null | no | The status line: "authority currently unavailable: <owner> lacks <right> on <scope>" after a denial, or why an ended authority stopped. Cleared by the next successful run. |
statusLineAt | string or null | no | |
SyncConfigResponseDto
| Property | Type | Required | Description |
|---|
adapterKey | one of "DOCUMENTATION", "TRACKER" | yes | |
authority | SyncAuthorityDto | yes | |
conflictStrategy | one of "INTERNAL_WINS", "EXTERNAL_WINS", "NEWEST_WINS", "MANUAL" | yes | |
createdAt | string | yes | |
direction | one of "PUSH", "PULL", "BIDIRECTIONAL" | yes | |
enabled | boolean | yes | |
id | string | yes | |
lastSyncAt | string or null | no | |
orgId | string | yes | |
paused | boolean | yes | |
projectId | string | yes | |
syncIntervalMs | number | yes | |
updatedAt | string | yes | |
SyncConfigResponseDtoDataArrayEnvelope
SyncConfigResponseDtoDataEnvelope
SyncConfigStatusDto
SyncExecutionResponseDto
| Property | Type | Required | Description |
|---|
executionId | string | yes | |
itemsFailed | number | yes | |
itemsProcessed | number | yes | |
itemsSkipped | number | yes | |
status | one of "RUNNING", "COMPLETED", "PARTIAL", "FAILED" | yes | |
SyncExecutionResponseDtoDataEnvelope
SyncExecutionSummaryDto
| Property | Type | Required | Description |
|---|
completedAt | string or null | no | |
errorCode | string or null | no | DURABLE_DELEGATION_AUTHORITY_UNAVAILABLE (denied: the next run may succeed), DURABLE_DELEGATION_ENDED (ended: needs authorising again), or another failure code. |
errorSummary | string or null | no | |
id | string | yes | |
itemsFailed | number | yes | |
itemsProcessed | number | yes | |
itemsSkipped | number | yes | |
startedAt | string | yes | |
status | one of "RUNNING", "COMPLETED", "PARTIAL", "FAILED" | yes | |
trigger | one of "MANUAL", "SCHEDULED" | yes | |
| Property | Type | Required | Description |
|---|
externalId | string | yes | External resource ID |
internalId | string | yes | Internal resource ID |
itemType | string | yes | Item type (kb_page, kb_space, artifact, etc.) |
SyncStatusResponseDto
| Property | Type | Required | Description |
|---|
configs | array of SyncConfigStatusDto | yes | |
mappingStats | map of number | yes | Mapping counts by sync status, across the project. |
SyncStatusResponseDtoDataEnvelope
TriggerAnalysisDto
| Property | Type | Required | Description |
|---|
connectionId | string | yes | The connection the project's documentation binding uses. |
TriggerAnalysisResponseDto
| Property | Type | Required | Description |
|---|
analysisId | string | yes | |
status | one of "SCANNING", "COMPLETED", "FAILED" | yes | |
TriggerAnalysisResponseDtoDataEnvelope
UpdateSyncConfigDto
| Property | Type | Required | Description |
|---|
conflictStrategy | one of "INTERNAL_WINS", "EXTERNAL_WINS", "NEWEST_WINS", "MANUAL" | no | |
direction | one of "PUSH", "PULL", "BIDIRECTIONAL" | no | Changing the direction changes what the schedule invokes; a held authorisation that does not lend exactly that is revoked and the schedule needs authorising again. |
enabled | boolean | no | |
syncIntervalMs | number | no | |