Forge migration REST API

This page documents the REST endpoints used by Forge apps to integrate with the app migration platform during server-to-cloud migrations.

Base path: /app/migration/forge/v1

Download Forge migration REST API

Update message status

• Method and path: POST /app/migration/forge/v1/message/{transferId}/status
• Summary: Update message status.
• Path parameters:
  • transferId (string, uuid) – required. Transfer ID as UUID.
• Request body (MessageProgress):
  • status (string) enum: SUCCESS, FAILED
  • messageIds (array<string, uuid>)
• Responses:
  • 200 OK

Example request body:

1
2
{
  "status": "SUCCESS",
  "messageIds": ["53f88ea7-a2d2-4dd2-9f36-2d8c43401b11"]
}

---

Find mappings by namespace and keys

• Method and path: POST /app/migration/forge/v1/mapping/{transferId}/find
• Summary: Find mapping values for specific server keys within a namespace.
• Path parameters:
  • transferId (string, uuid) – required. Transfer ID as UUID.
• Query parameters:
  • namespace (string) – required.
• Request body:
  • Array of server keys array<string> (unique items).
• Responses:
  • 200 OK, body is an object mapping server keys to values: Record<string, string>

Example request body:

1
2
["10000", "10001"]

Example response body:

1
2
{
  "10000": "10023",
  "10001": "10024"
}

---

Add log message

• Method and path: POST /app/migration/forge/v1/log/{transferId}
• Summary: Add a log message from the Forge app (shown in customer-visible migration logs).
• Path parameters:
  • transferId (string, uuid) – required. Transfer ID as UUID.
• Request body (ForgeAppLog):
  • message (string, maxLength 65536)
• Responses:
  • 200 OK

Example request body:

1
2
{ "message": "Processed 250 issues for container 3ac7..." }

---

Get mappings (paged)

• Method and path: GET /app/migration/forge/v1/mapping/{transferId}/page
• Summary: Returns mappings for a given namespace.
• Path parameters:
  • transferId (string, uuid) – required.
• Query parameters:
  • namespace (string) – required.
  • lastEntity (string) – optional. Cursor for pagination.
  • pageSize (integer) – optional. Default 1200, min 1, max 1200.
• Responses:
  • 200 OK → MigrationMappingDto

Example response body:

1
2
{
  "meta": {
    "pageSize": 1200,
    "hasNext": false,
    "lastEntity": "1001"
  },
  "items": {
    "1000": "10023",
    "1001": "10024"
  }
}

---

Get app data (signed URL metadata)

• Method and path: GET /app/migration/forge/v1/data/{s3Key}
• Summary: Returns an object containing a signed URL (and related metadata) to retrieve app data.
• Path parameters:
  • s3Key (string, uuid) – required.
• Responses:
  • 200 OK → Record<string, string>

Example response body:

1
2
{
  "url": "https://..."
}

---

Download app data payload

• Method and path: GET /app/migration/forge/v1/data/{s3Key}/payload
• Summary: Returns the app data payload as a binary stream.
• Path parameters:
  • s3Key (string, uuid) – required.
• Responses:
  • 200 OK → application/octet-stream (binary)

---

Get containers (paged)

• Method and path: GET /app/migration/forge/v1/container/{transferId}/page
• Summary: Returns containers for a given transferId and containerType.
• Path parameters:
  • transferId (string, uuid) – required.
• Query parameters:
  • containerType (string) – required. One of: JiraProject, ConfluenceSpace, Site.
  • lastEntity (string, uuid) – optional. Cursor for pagination.
  • pageSize (integer) – optional. Default 250, min 1, max 250.
• Responses:
  • 200 OK → ContainerByPageResponse

ContainerByPageResponse:

1
2
{
  "meta": {
    "pageSize": 250,
    "hasNext": false,
    "lastEntity": "string"
  },
  "containers": [
    { "type": "string" },
    { "transfers": [PlatformTransfer] }
  ]
}

---

List app data keys

• Method and path: GET /app/migration/forge/v1/data/{transferId}/all
• Summary: Returns all uploaded file keys for a transfer ID.
• Path parameters:
  • transferId (string, uuid) – required.
• Responses:
  • 200 OK → Array of ForgeFileMappingDto

Example response body:

1
2
[
    {
        "key": "dbc96598-fc84-4c91-9e60-2fc01f705de7",
        "s3Key": "dbc96598-fc84-4c91-9e60-2fc01f705de7",
        "label": "my-data-export"
    },
    {
        "key": "abc86558-jg32-5c82-9e60-2fc01f705de7",
        "s3Key": "abc86558-jg32-5c82-9e60-2fc01f705de7",
        "label": "my-data-export"
    }
]

---

Schemas

Below are the common schema definitions referenced by the endpoints above.

MessageProgress

1
2
{
  "status": "SUCCESS | FAILED",
  "messageIds": ["uuid", "uuid", "..."]
}

ForgeAppLog

1
2
{ "message": "string" }

MigrationMappingDto

1
2
{
  "meta": MigrationMappingMeta,
  "items": { "<serverKey>": "<value>" }
}

MigrationMappingMeta

1
2
{
  "pageSize": 0,
  "hasNext": false,
  "lastEntity": "string"
}

ForgeFileMappingDto

1
2
{
  "key": "string",
  "s3Key": "string",
  "label": "string"
}

ContainerByPageResponse

1
2
{
  "meta": ContainerResponseMeta,
  "containers": [ ContainerV1 ]
}

ContainerResponseMeta

1
2
{
  "pageSize": 0,
  "hasNext": false,
  "lastEntity": "string"
}

ContainerV1

1
2
{ "type": "string?", "transfers": [PlatformTransfer]? }

PlatformTransfer

1
2
{
  "transferId": "string",
  "operationKey": "string",
  "status": "string?",
  "statusMessage": "string?",
  "progressPercentage": "number?",
  "progressMessage": "string?",
  "progressProperties": {
    "additionalProperty": "any"
  }?,
  "lastUpdatedAt": "string?"
}