Sync Trigger API | Sync Bridge for Jira Cloud | mgm Marketplace App Documentation

📘 What you will learn here

On this page you will learn how to call the Sync Trigger API to push or pull 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.

The Sync Trigger API is included in the Advanced and Evaluation (trial) editions. On Standard, calls are refused with 403. See License Editions.

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 to push through the API, or Pull to pull through the API.
In the Push or Pull panel's Triggers, turn on API, then select Show details next to it. Push and pull each have their own API switch.
Copy the URL shown under Endpoint.
Under Push API tokens or Pull API tokens, create a token for the calling service. A push token can only push, and a pull token can only pull.
Select View example request to copy a ready-made curl command with the rule ID and direction 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 or pull, for example `PROJ-123`. The numeric work item ID also works, for example when an automation passes `{{issue.id}}`.
`direction`	string	No	`"push"` or `"pull"` (lowercase). Default: `"push"`. The token must be a token for this direction, and the rule's API trigger for this direction must be on.

Other fields are ignored.

JSON

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

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","direction":"push"}'

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}}",
  "direction": "push"
}

What happens after a successful call

Push: 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.

Pull: a 200 response means the pull was started, or a sync for this work item is already running. If the pull can't start, the call returns 422 with the reason:

Message	What to do
We couldn't find or read work item <key>. Check the key or ID and try again.	Check `issueKey`, and that the work item exists on this Jira site.
This sync rule is turned off.	Turn the rule on.
Pull is turned off for this sync rule.	Turn on Pull in the rule.
Nothing to pull. This sync rule doesn't pull any fields, comments, attachments or status.	Set at least one field mapping, comments, attachments or status to sync from the target.
Sync is turned off for this work item.	Turn sync on for the work item. See Turn Sync On or Off for a Work Item.
There's no linked work item to pull from yet. Push this work item first.	Pull only updates work items that are already linked. Push the work item first.
A message that the work item or the linked work item is archived or unreachable	Restore the work item, or unlink it in the Sync Bridge panel.

An API pull doesn't run again for a work item that hasn't changed on the other site since the last pull, so an automation that fires on every update can't start a loop.

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.
`400`	`{"error": "direction must be \"push\" or \"pull\"."}`	`direction` is set to anything other than `push` or `pull`.
`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 token is for the other direction (for example a push token in a pull call); the rule doesn't exist; the rule's API trigger for this direction 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.
`403`	`{"error": "The web trigger (API) needs an Advanced license. Upgrade the Sync Bridge license to use it."}`	The site's Sync Bridge license is Standard, which doesn't include the API. See License Editions.
`400`	`{"error": "issueKey is required in the request body."}`	`issueKey` is missing, empty or not a string.
`422`	`{"error": "<reason>"}`	Pull only: the pull can't start. See the reasons above.
`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, that the token is for the direction you call, and that the rule's API trigger for that direction is turned on.
410: ask a Jira admin to create a new token.
402: ask a Jira admin to renew the license.
403: ask a Jira admin to upgrade the Sync Bridge license to Advanced.
422: fix the cause given in the message, for example push the work item first. Retrying won't help until then.
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 its own direction: a push token pushes, a pull token pulls, and only for work items that match that rule.
A Jira admin can revoke a token at any time. It stops working immediately. See API Tokens.