# Create links

`POST /v1/environments/{environmentId}/operations/links`

Available as MCP tool `create-links` (Write).

Subscription endpoints allow you to review, compare, and manage subscriptions and their related  links to assets (i.e., filters, config modifiers, translation sets).

You must be a member of the environment and be assigned to an engineer role to manage subscriptions. [Learn about roles](https://docs.redoxengine.com/permalink/1OBel3inQAjAnDbgd9QLzM).

### Create links

Add one or more subscription link(s) for the selected asset(s). A link’s settings can be independent or taken from an existing link using \`fromLink\`.

The request contains a list of links for one or more asset types. To link one asset to multiple subscriptions, include a `link` entry for each one. For example, an asset with 3 subscription links should have 3 entries in the list. 

A filter can only have one subscription link. 

## Request parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environmentId` | path | string | Yes | Identifies the specific environment that you're operating in or on behalf of. |

## Request body

Contains the links to create within the specified environment.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `links` | Array of object | Yes | Lists the links to create (max allowed is 50). The same asset may appear in several entries, one per subscription. |
| `links[].asset` | object | Yes | Identifies the asset to link. It must belong to the specified environment. |
| `links[].asset.id` | string (uuid) | Yes | Contains the unique identifier of the asset. |
| `links[].asset.type` | string | Yes | Possible values: configModifier, filter, translationSet |
| `links[].subscription` | object | Yes | Identifies the subscription to link the asset to based on its source, destination, and data model. |
| `links[].subscription.source` | object | Yes | Specifies the source of the subscription that an asset is or should be linked to. |
| `links[].subscription.source.id` | string (uuid) | Yes | Contains the unique identifier of the source. |
| `links[].subscription.destination` | object | Yes | Specifies the destination of the subscription that an asset is or should be linked to. |
| `links[].subscription.destination.id` | string (uuid) | Yes | Contains the unique identifier of the destination. |
| `links[].subscription.dataModel` | string | Yes | Specifies the Redox data model that the link applies to or should apply to. |
| `links[].fromLink` | object | No | Identifies an existing link for the same asset type to take settings from. Any value in `linkSettings` overrides the respective setting taken from this link. |
| `links[].fromLink.id` | string (uuid) | Yes | Contains the unique identifier of the link for a specified asset. |
| `links[].linkSettings` | object | No | Contains the link's settings, which depend on the asset type. A config modifier link accepts `expectedDataModel`, `eventTypes`, `ownedBy`, and `processingLocation`; a translation set link accepts `expectedDataModel`, `direction`, `processingLocation`, and `paths`; a filter link has no settings. A setting that doesn't apply to the asset type fails the whole request. When you give `fromLink`, any setting here overrides the setting taken from that link. |
| `links[].linkSettings.expectedDataModel` | string | No | Specifies the data model when it is expected to differ from the subscription's data model. Defaults to the subscription's data model. |
| `links[].linkSettings.eventTypes` | Array of string, nullable | No | For config modifier links only, specifies the event types of the data model that the link applies to. Set to `null` to apply the config modifier's link to every event type. |
| `links[].linkSettings.ownedBy` | string | No | For config modifier links only, indicates whether the source or destination system owns the link. Inferred from the subscription when omitted. Possible values: source, destination |
| `links[].linkSettings.processingLocation` | string | No | Identifies where a link will be applied during log processing. There are up to four stages that an asset can be linked to, depending on whether you own either the source, the destination, or both. Possible values: source-request, destination-request, source-response, destination-response |
| `links[].linkSettings.direction` | string | No | Indicates the direction in which the translation set is or should be linked. This can be either `from-to` (translates a "from" value into a "to" value), or `to-from` (tranlates a "to" value into a "from" value). Possible values: from-to, to-from |
| `links[].linkSettings.paths` | Array of object | No | Lists the field paths linked to a translation set. These paths must be unique on the path property. |
| `links[].linkSettings.paths[].dataType` | string | No | Describes the format of the data found at the path location. |
| `links[].linkSettings.paths[].title` | string | No | Specifies a human-readable title for the field path. |
| `links[].linkSettings.paths[].path` | string | No | Specifies the path in a message to the location of the data to be translated. The path must always start with a $ to be considered valid. |

## Request example

_Generated from the schema: the values are placeholders, not a real payload._

```bash
curl 'https://api.redoxengine.com/platform/v1/environments/{environmentId}/operations/links' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "links": [
    {
      "asset": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "type": "configModifier"
      },
      "subscription": {
        "source": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        },
        "destination": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        },
        "dataModel": "PatientAdmin"
      },
      "fromLink": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      },
      "linkSettings": {
        "expectedDataModel": "PatientAdmin",
        "eventTypes": [
          "string"
        ],
        "ownedBy": "source",
        "processingLocation": "source-request",
        "direction": "to-from",
        "paths": [
          {
            "dataType": "string",
            "title": "Custom Path",
            "path": "$.Allergies[*].Type.Code"
          }
        ]
      }
    }
  ]
}'
```

## Responses

### 200

Contains a payload with the outcome (i.e., succeeded or failed) of each new link added or existing link used. A `200` means Redox successfully processed the request, but doesn't necessarily indicate a successful outcome for each individual link. Check the `failures` array for details.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `meta` | object | No |  |
| `meta.version` | string | No | Lists the major and minor version number for the format of the returned payload. The payload format or shape may change between minor versions, like including additional or extended fields in later versions. We include the version data in each response so that you have the option to handle the signaled differences. |
| `payload` | object | No |  |
| `payload.links` | Array of object | No | Lists the links that now exist, whether they were created by this request or already existed. |
| `payload.links[].asset` | object | No | Identifies the asset to link. It must belong to the specified environment. |
| `payload.links[].asset.id` | string (uuid) | Yes | Contains the unique identifier of the asset. |
| `payload.links[].asset.type` | string | Yes | Possible values: configModifier, filter, translationSet |
| `payload.links[].link` | object | No |  |
| `payload.links[].link.id` | string (uuid) | No | Contains the unique identifier of the link for a specified asset. |
| `payload.links[].link.subscription` | object | No | Identifies the subscription to link the asset to based on its source, destination, and data model. |
| `payload.links[].link.subscription.source` | object | Yes | Specifies the source of the subscription that an asset is or should be linked to. |
| `payload.links[].link.subscription.source.id` | string (uuid) | Yes | Contains the unique identifier of the source. |
| `payload.links[].link.subscription.destination` | object | Yes | Specifies the destination of the subscription that an asset is or should be linked to. |
| `payload.links[].link.subscription.destination.id` | string (uuid) | Yes | Contains the unique identifier of the destination. |
| `payload.links[].link.subscription.dataModel` | string | Yes | Specifies the Redox data model that the link applies to or should apply to. |
| `payload.links[].action` | string | No | Indicates whether this request created the link or found an existing one that went unchanged. An `unchanged` link reports the existing link's ID. Possible values: created, unchanged |
| `payload.failures` | Array of object | No | Lists any links that weren't added, along with the error that prevented it. See `error.meta.isTransient` to learn whether you can safely retry adding a link. This array is empty when every link was added successfully. |
| `payload.failures[].asset` | object | No | Identifies the asset to link. It must belong to the specified environment. |
| `payload.failures[].asset.id` | string (uuid) | Yes | Contains the unique identifier of the asset. |
| `payload.failures[].asset.type` | string | Yes | Possible values: configModifier, filter, translationSet |
| `payload.failures[].link` | object | No | Identifies the intended subscription of the failed link so the correct entry can be retried. |
| `payload.failures[].link.subscription` | object | No | Identifies the subscription to link the asset to based on its source, destination, and data model. |
| `payload.failures[].link.subscription.source` | object | Yes | Specifies the source of the subscription that an asset is or should be linked to. |
| `payload.failures[].link.subscription.source.id` | string (uuid) | Yes | Contains the unique identifier of the source. |
| `payload.failures[].link.subscription.destination` | object | Yes | Specifies the destination of the subscription that an asset is or should be linked to. |
| `payload.failures[].link.subscription.destination.id` | string (uuid) | Yes | Contains the unique identifier of the destination. |
| `payload.failures[].link.subscription.dataModel` | string | Yes | Specifies the Redox data model that the link applies to or should apply to. |
| `payload.failures[].error` | object | No | Explains why one item in a bulk request failed. The overall request still returns `200`. A request that's rejected before any work starts (e.g., due to a malformed body) returns `400` instead. |
| `payload.failures[].error.id` | string | Yes | Contains a unique identifier for this error instance. |
| `payload.failures[].error.code` | string | Yes | Identifies the error type, which can be used to find relevant troubleshooting information. |
| `payload.failures[].error.title` | string | Yes | Displays the high-level error message. |
| `payload.failures[].error.detail` | string | Yes | Contains the specific error details for this item. |
| `payload.failures[].error.meta` | object | No | Contains additional details about the failure. Some errors add other properties, such as the ID of an asset that was partially created. |
| `payload.failures[].error.meta.isTransient` | boolean | No | Indicates whether retrying this item as-is might succeed. `true` means the failure was temporary (e.g., a timeout), so you can retry the item. `false` means the item will continue to fail until you correct the issue (e.g., the asset doesn't exist or its name is a duplicate). When absent, the failure wasn't classified; review `detail` before retrying. |

_Generated from the schema: the values are placeholders, not a real payload._

```json
{
  "meta": {
    "version": "1.0.0"
  },
  "payload": {
    "links": [
      {
        "asset": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "type": "configModifier"
        },
        "link": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "subscription": {
            "source": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            },
            "destination": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            },
            "dataModel": "PatientAdmin"
          }
        },
        "action": "created"
      }
    ],
    "failures": [
      {
        "asset": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "type": "configModifier"
        },
        "link": {
          "subscription": {
            "source": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            },
            "destination": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            },
            "dataModel": "PatientAdmin"
          }
        },
        "error": {
          "id": "string",
          "code": "asset.not.found",
          "title": "Not Found",
          "detail": "string",
          "meta": {
            "isTransient": true
          }
        }
      }
    ]
  }
}
```

### 400

Bad Request

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.error` | object | No | Contains the error message details. |
| `payload.error.id` | string | No | Contains a unique identifier for the given error instance. |
| `payload.error.title` | string | No | Displays the high-level error message, typically something succinct like `Bad Request`. |
| `payload.error.code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |
| `payload.error.detail` | string | No | Contains the specific error details for this message. |
| `payload.error.status` | number | No | Displays the corresponding HTTP status code for the error. |
| `payload.error.transient` | boolean | No | Describes whether the error will resolve itself. If `true`, no further action needs to be taken. If `false`, you may need to troubleshoot on your end to resolve the issue before the error can be processed. |

```json
{
  "payload": {
    "error": {
      "title": "Bad Request",
      "code": "validation.error.bad.request",
      "detail": "Error details",
      "status": 400,
      "transient": false
    }
  }
}
```

### 403

Forbidden

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.errors` | Array of object | No |  |
| `payload.errors[].title` | string | No | Displays the high-level error message, typically something succinct like `Forbidden`. |
| `payload.errors[].code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |

```json
{
  "payload": {
    "errors": [
      {
        "title": "Forbidden",
        "code": "authorization.forbidden"
      }
    ]
  }
}
```

### 500

Internal Server Error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.error` | object | No | Contains the error message details. |
| `payload.error.title` | string | No | Displays the high-level error message, typically something succinct like `Failed in step X`. |
| `payload.error.code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |
| `payload.error.detail` | string | No | Contains the specific error details for this message. |
| `payload.error.status` | number | No | Displays the corresponding HTTP status code for the error. |
| `payload.error.transient` | boolean | No | Describes whether the error will resolve itself. If `true`, no further action needs to be taken. If `false`, you may need to troubleshoot on your end to resolve the issue before the error can be processed. |

```json
{
  "payload": {
    "error": {
      "title": "Internal Server Error",
      "code": "failed.db.lookup",
      "detail": "Error details",
      "status": 500,
      "transient": true
    }
  }
}
```
