# Create subscription

`POST /v1/environments/{environmentId}/subscriptions`

Available as MCP tool `create-subscription` (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 subscription

Create a new subscription in the specified environment.

## 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source` | object | Yes |  |
| `source.id` | string (uuid) | Yes | Identifies the unique identifier for the source that initiates the data exchange. |
| `destination` | object | Yes |  |
| `destination.id` | string (uuid) | Yes | Identifies the unique identifier for the destination that receives the data. |
| `dataModel` | string | Yes | Specifies the Redox data model used to exchange data between the source and destination. |

## Request example

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

```bash
curl 'https://api.redoxengine.com/platform/v1/environments/{environmentId}/subscriptions' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "source": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  },
  "destination": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  },
  "dataModel": "PatientAdmin"
}'
```

## Responses

### 200

Contains a payload object with details of the newly created subscription.

| 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.subscription` | object | No | Contains details about the subscription. |
| `payload.subscription.source` | object | No |  |
| `payload.subscription.source.id` | string (uuid) | No | Contains the unique identifier of the source. |
| `payload.subscription.source.environmentFlag` | string | No | Indicates the environment type of the source. |
| `payload.subscription.destination` | object | No |  |
| `payload.subscription.destination.id` | string (uuid) | No | Contains the unique identifier of the destination. |
| `payload.subscription.destination.environmentFlag` | string | No | Indicates the environment type of the destination. |
| `payload.subscription.dataModel` | string | No | Specifies the Redox data model used for this subscription. |
| `payload.subscription.deletedAt` | string (date-time), nullable | No | Indicates when the subscription was deleted, if applicable. |

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

```json
{
  "meta": {
    "version": "1.0.0"
  },
  "payload": {
    "subscription": {
      "source": {
        "id": "3f7c5e24-91d4-4b55-9b65-4a6e2f3ea9c2",
        "environmentFlag": "Production"
      },
      "destination": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "environmentFlag": "Production"
      },
      "dataModel": "PatientAdmin",
      "deletedAt": null
    }
  }
}
```

### 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
    }
  }
}
```
