---
title: "Submit Remote Link data"
method: POST
path: "/rest/remotelinks/1.0/bulk"
tags: ["Remote Links"]
---

# Submit Remote Link data

`POST /rest/remotelinks/1.0/bulk`

Update / insert Remote Link data.

Remote Links are identified by their ID, existing Remote Link data for the same ID will be replaced if it
exists and the updateSequenceId of existing data is less than the incoming data.

Submissions are performed asynchronously. Submitted data will eventually be available in Jira; most updates are
available within a short period of time, but may take some time during peak load and/or maintenance times.
The `getRemoteLinkById` operation can be used to confirm that data has been stored successfully (if needed).

In the case of multiple Remote Links being submitted in one request, each is validated individually prior to
submission. Details of which Remote LInk failed submission (if any) are available in the response object.

## Request body

- object — The payload used to submit (update / insert) Remote Link data.
  - `properties` object — Properties assigned to Remote Link data that can then be used for delete / query operations. Examples might be an account or user ID that can then be used to clean up data if an account is removed from the Provider system. Properties are supplied as key/value pairs, a maximum of 5 properties can be supplied, and keys must not contain ':' or start with '_'.
  - `remoteLinks` object[], required — A list of Remote Links to submit to Jira. Each Remote Link may be associated with one or more Jira issue keys, and will be associated with any properties included in this request.
    - `schemaVersion` '1.0' — The schema version used for this data. Placeholder to support potential schema changes in the future.
    - `id` string, required — The identifier for the Remote Link. Must be unique for a given Provider.
    - `updateSequenceNumber` integer, required — An ID used to apply an ordering to updates for this Remote Link in the case of out-of-order receipt of update requests. It must be a monotonically increasing number. For example, epoch time could be one way to generate the `updateSequenceNumber`. Updates for a Remote Link that is received with an `updateSqeuenceNumber` less than or equal to what is currently stored will be ignored.
    - `displayName` string, required — The human-readable name for the Remote Link. Will be shown in the UI.
    - `url` string, uri, required — The URL to this Remote Link in your system.
    - `type` 'document' | 'alert' | 'test' | 'security' | 'logFile' | 'prototype' | 'coverage' | 'bugReport' | 'other', required — The type of the Remote Link. The current supported types are 'document', 'alert', 'test', 'security', 'logFile', 'prototype', 'coverage', 'bugReport' and 'other'
    - `description` string — An optional description to attach to this Remote Link. This may be anything that makes sense in your system.
    - `lastUpdated` string, date-time, required — The last-updated timestamp to present to the user as a summary of when Remote Link was last updated.
    - `associations` union[] — The entities to associate the Remote Link information with.
      - union
        - IssueIdOrKeysAssociation — An association type referencing issues in Jira.
          - `associationType` 'issueKeys' | 'issueIdOrKeys', required — Defines the association type.
          - `values` string[], required — The Jira issue keys or IDs to associate the entity with. The number of values counted across all associationTypes must not exceed a limit of 500.
        - ServiceIdOrKeysAssociation — An association type referencing service ID or keys.
          - `associationType` 'serviceIdOrKeys', required — Defines the association type.
          - `values` string[], required — The service ID or keys to associate the entity with. The number of values counted across all associationTypes must not exceed a limit of 500.
    - `status` object — The status of a Remote Link.
      - `appearance` 'default' | 'inprogress' | 'moved' | 'new' | 'removed' | 'prototype' | 'success', required — Appearance is a fixed set of appearance types affecting the colour of the status lozenge in the UI. The colours they correspond to are equivalent to atlaskit's [Lozenge](https://atlaskit.atlassian.com/packages/core/lozenge) component.
      - `label` string, required — The human-readable description for the Remote Link status. Will be shown in the UI.
    - `actionIds` string[] — Optional list of actionIds. They are associated with the actions the provider is able to provide when they registered. Indicates which actions this Remote Link has. If any actions have a templateUrl that requires string substitution, then `attributeMap` must be passed in.
    - `attributeMap` object — Map of key/values (string to string mapping). This is used to build the urls for actions from the templateUrl the provider registered their available actions with.
  - `providerMetadata` object — Information about the provider. This is useful for auditing, logging, debugging, and other internal uses. It is not considered private information. Hence, it may not contain personally identifiable information.
    - `product` string — An optional name of the source of the Remote Links data.

## Response `202`

Submission accepted. Each submitted Remote Link that is of a valid format will be eventually available in
Jira.

Details of which Remote Links were submitted and which failed submission (due to data format problems etc.)
are available in the response object.

- object — The result of a successful `submitRemoteLinks` request.
  - `acceptedRemoteLinks` string[] — The IDs of Remote Links that have been accepted for submission. A Remote Link may be rejected if it was only associated with unknown issue keys, unknown service IDs, or if the submitted data for that Remote Link does not match the required schema. Note that a Remote Link that isn't updated due to it's `updateSequenceNumber` being out of order is not considered a failed submission.
  - `rejectedRemoteLinks` object — Details of Remote Links that have not been accepted for submission, usually due to a problem with the request data. A Remote Link may be rejected if it was only associated with unknown issue keys, unknown service IDs, or if the submitted data for the Remote Link does not match the required schema. The object (if present) will be keyed by Remote Link ID and include any errors associated with that Remote Link that have prevented it being submitted.
  - `unknownAssociations` union[] — Issue keys or services IDs or keys that are not known on this Jira instance (if any).
    - union
      - IssueIdOrKeysAssociation — An association type referencing issues in Jira.
        - `associationType` 'issueKeys' | 'issueIdOrKeys', required — Defines the association type.
        - `values` string[], required — The Jira issue keys or IDs to associate the entity with. The number of values counted across all associationTypes must not exceed a limit of 500.
      - ServiceIdOrKeysAssociation — An association type referencing service ID or keys.
        - `associationType` 'serviceIdOrKeys', required — Defines the association type.
        - `values` string[], required — The service ID or keys to associate the entity with. The number of values counted across all associationTypes must not exceed a limit of 500.

## Other responses

- `400` — Request has incorrect format. Note that in the case of an individual Remote Link having an invalid format (rather than the request as a whole) the response for the request will be a 202 and details of the invalid Remote Link will be contained in the response object.
- `401` — Missing a JWT token, or token is invalid.
- `403` — The JWT token used does not correspond to an app that defines the `jiraRemoteLinkInfoProvider` module, or the app does not define the 'WRITE' scope.
- `413` — Data is too large. Submit fewer Remote Links in each payload.
- `429` — API rate limit has been exceeded.
- `503` — Service is unavailable due to maintenance or other reasons.
- `default` — An unknown error has occurred.

---

[API](https://skmtc.net/atlassian/apis/jira-software-cloud-api.md) · [All operations](https://skmtc.net/atlassian/apis/jira-software-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/jira-software-cloud-api/versions/4e108d54b990/schema)