Sync Trigger API | mgm Marketplace App Documentation

📘 What you will learn here

On this page you will learn how to call the Sync Trigger API to push one work item through one sync rule from another service, including the endpoint, request body, responses and error handling.

Use it from Jira automation, a CI pipeline, a script or any tool that can send an HTTPS request. To create the token you need, see API Tokens.

Before you start

A Jira admin needs to set up the sync rule:

In the Sync Bridge admin page, open Sync rules and open the rule.
On the Configuration tab, under Sync direction, make sure Push is turned on.
In the Push panel's Triggers, turn on API, then select Show details next to it.
Copy the URL shown under Endpoint.
Under API tokens, create a token for the calling service.
Select View example request to copy a ready-made curl command with the rule ID already filled in.

Endpoint

Item	Value
Method	`POST`
URL	The URL shown under Endpoint in the rule. It's the same for every rule and every caller on this Jira site. The rule is selected by `configId` in the body, and the caller is identified by the token.
Authentication	Header `X-Sync-Secret: <API token>`. The header name isn't case-sensitive.
Request body	JSON. Send `Content-Type: application/json`.

Request body

Field	Type	Required	Description
`configId`	string	Yes	The ID of the sync rule to run. The token must belong to this rule. The ID is filled in by View example request, appears in the address of the rule in the admin page, and is shown as Rule ID when you hover the info icon next to the rule name in the Sync Bridge panel.
`issueKey`	string	Yes	The work item on this Jira site to push, for example `PROJ-123`. The numeric work item ID also works, for example when an automation passes `{{issue.id}}`.

Other fields are ignored.

JSON

{
  "configId": "<rule ID>",
  "issueKey": "PROJ-123"
}

Example with curl

Bash

curl -X POST "<endpoint URL>" \
  -H "x-sync-secret: <your API token>" \
  -H "Content-Type: application/json" \
  -d '{"configId":"<rule ID>","issueKey":"PROJ-123"}'

Example with Jira automation

In your automation rule, add the Send web request action.
Set the web request URL to the endpoint URL and the method to POST.
Add the header X-Sync-Secret with your API token as its value. Mark it as hidden if your automation tool offers that.
Set the body to custom data:

JSON

{
  "configId": "<rule ID>",
  "issueKey": "{{issue.key}}"
}

What happens after a successful call

A 200 response means the request was accepted. The sync then runs in the background, in the same way as a manual push. The response doesn't tell you whether anything was synced. Nothing is pushed, and the call still returns 200, when:

The rule is turned off, or push is turned off for it.
The work item doesn't exist, or doesn't match the rule's source scope.
Sync is turned off for this work item for this rule (see Turn Sync On or Off for a Work Item).
The work item or its linked work item is known to be archived or unreachable.

To see the result, check the Sync History tab on the work item. API runs show API · token name as the trigger. Jira admins can also check the Sync History (admin page).

Responses

All responses are JSON. Checks run in the order below, so the first problem found is the one reported.

Status	Body	When
`400`	`{"error": "The request body isn't valid JSON."}`	The body can't be parsed as JSON.
`400`	`{"error": "configId is required in the request body"}`	`configId` is missing, empty or not a string.
`401`	`{"error": "Missing or invalid token. Send a valid token in the X-Sync-Secret header."}`	Any of these: the header is missing; the token is wrong or revoked; the token belongs to a different rule; the rule doesn't exist; the rule's API trigger is turned off. The response is the same in every case on purpose.
`410`	`{"error": "This token expired on <date>. Create a new token in the sync rule.", "expiresAt": "<date>"}`	The token is valid but has expired. `expiresAt` is an ISO 8601 timestamp.
`402`	`{"error": "The Sync Bridge license for this site is inactive."}`	The Sync Bridge license on this Jira site is inactive.
`400`	`{"error": "issueKey is required in the request body."}`	`issueKey` is missing, empty or not a string.
`500`	`{"error": "Something went wrong. Try again later."}`	An unexpected error while starting the sync. Retry later.
`200`	`{"ok": true}`	The request was accepted.

Errors and retries

400: fix the request. Retrying the same request won't help.
401: check the token, the configId, and that the rule's API trigger is turned on.
410: ask a Jira admin to create a new token.
402: ask a Jira admin to renew the license.
500: retry later, with a delay between attempts.

Sync Bridge doesn't add its own rate limit. Limits of the Atlassian Forge platform for web triggers apply.

Security

Treat the token like a password. Store it in a secret store and send it only in the X-Sync-Secret header.
Each token can trigger only its own rule, and only a push of work items that match that rule.
A Jira admin can revoke a token at any time. It stops working immediately. See API Tokens.