---
title: "Publish a Module"
method: POST
path: "/modules"
tags: ["modules"]
---

# Publish a Module

`POST /modules`

## Request

- Base URL: `https://example.scalr.io/api/iacp/v3`
- URL: `https://example.scalr.io/api/iacp/v3/modules`
- Auth: HTTP bearer

This endpoint creates a Module from a VCS repository.

The module's source code directory should follow the
[standard module structure](https://www.terraform.io/docs/language/modules/develop/structure.html).

Scalr extracts various meta information from the module's source:
* It's important to provide each `variable` and `output` blocks with a meaningful descriptions, as they
will be displayed in a Module and Workspace Variables pages for your internal users.
* README or README.md file will be displayed on a Module page.
* Nested modules from `modules/` directory will be searchable and available though the Registry just
like top-level modules.

Modules can be published on both `account` and `environment` scopes.
If neither scope is specified in the request body, the module will be published in the
same scope that the related `vcs-provider` is published.

## Request body

- ModuleDocument: JSON:API Document. see: https://jsonapi.org/format/#document-structure
  - `data` Module: A terraform module in the [Private Module Registry](/docs/private-module-registry).
    - `attributes` object
      - `created-at` string, date-time: The resource creation timestamp.
      - `description` string: The description of the module. By default, this is taken from the VCS repository description. For mono repos you likely want to override this behavior by passing this argument in a [Create Module](modules.html#create-a-module) operation.
      - `docker-image` string, nullable: Docker/OCI image repository path for OCI-backed modules.
      - `error-message` string, nullable: This field contains the error description, when this module's status is `errored`.
      - `name` string: The module name.
      - `provider` string: A name of a system, this module was written for. For multi-cloud modules this argument should match terraform provider name (ex: `aws` or `google`), in other cases the convention is to name it `system`
      - `source` string: The `source` by which the module should be addressed from a HCL template.
      - `source-type` 'vcs' | 'docker': The upstream source type for the module.
      - `status` 'no_version_tags' | 'pending' | 'setup_complete' | 'errored': The Module's current status. Initial status: * `pending` - The initial status of a module once it has been created. Now Scalr will download the code from the VCS, and create a `module-version` resource for each matching Git tag. Ending statuses: * `no_version_tags` - a Module has been created, however the Module source repository has no tags. * `setup_complete` - a Module has been created, and at least one ModuleVersion has been successfully uploaded. Scalr assigns this status while some module-versions upload might be still in-progress. If you want to ensure a specific version was uploaded, you can poll [List Module Versions](module-versions.html#list-module-versions) for the `ok` status. * `errored` - Module has been created, however its synchronization has failed. Attribute `error-message` contains the details.
      - `vcs-repo` object, nullable
        - `identifier` string, required: A reference to the module's VCS repository. For GitHub, GitHub Enterprise and GitLab the format is `<org>/<repo>`. Azure DevOps Services has the format `<org>/<project>/<repo>`.
        - `path` string: The repository sub-directory where the module source is located. If omitted or submitted as an empty string, this defaults to the repository's root.
        - `tag-prefix` string: Specify this attribute when a module's releases are namespaced within a repository's Git tags. This is usually the case for a mono repos with individually versioned components. For example if your module is tagged `my-module/v1.0.0` it's `tag_prefix` is `my-module/`.
    - `id` string
    - `links` object
      - `self` string
    - `relationships` object
      - `account` object: The relationship `account` is deprecated. Use `namespace` instead.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'accounts' | '', required
      - `created-by` object: The user who has created the module.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'users' | '', required
      - `docker-integration` object: Docker registry connection used by OCI-backed modules.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'docker-integrations' | '', required
      - `environment` object: The relationship `environment` is deprecated. Use `namespace` instead.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'environments' | '', required
      - `latest-module-version` object: The module's latest version.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'module-versions' | '', required
      - `module-version` object: The module's latest successful version.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'module-versions' | '', required
      - `module-versions` object: The IDs of the module versions.
        - `data` object[], nullable, required
          - `id` string, required
          - `type` 'module-versions' | '', required
      - `namespace` object: The module namespace this module belongs to.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'module-namespaces' | '', required
      - `vcs-provider` object: The module's VCS provider.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'vcs-providers' | '', required
    - `type` 'modules', required
  - `included` object[]
  - `meta` object

## Response `201`

Successfully created module.

- ModuleDocument: JSON:API Document. see: https://jsonapi.org/format/#document-structure
  - `data` Module: A terraform module in the [Private Module Registry](/docs/private-module-registry).
    - `attributes` object
      - `created-at` string, date-time: The resource creation timestamp.
      - `description` string: The description of the module. By default, this is taken from the VCS repository description. For mono repos you likely want to override this behavior by passing this argument in a [Create Module](modules.html#create-a-module) operation.
      - `docker-image` string, nullable: Docker/OCI image repository path for OCI-backed modules.
      - `error-message` string, nullable: This field contains the error description, when this module's status is `errored`.
      - `name` string: The module name.
      - `provider` string: A name of a system, this module was written for. For multi-cloud modules this argument should match terraform provider name (ex: `aws` or `google`), in other cases the convention is to name it `system`
      - `source` string: The `source` by which the module should be addressed from a HCL template.
      - `source-type` 'vcs' | 'docker': The upstream source type for the module.
      - `status` 'no_version_tags' | 'pending' | 'setup_complete' | 'errored': The Module's current status. Initial status: * `pending` - The initial status of a module once it has been created. Now Scalr will download the code from the VCS, and create a `module-version` resource for each matching Git tag. Ending statuses: * `no_version_tags` - a Module has been created, however the Module source repository has no tags. * `setup_complete` - a Module has been created, and at least one ModuleVersion has been successfully uploaded. Scalr assigns this status while some module-versions upload might be still in-progress. If you want to ensure a specific version was uploaded, you can poll [List Module Versions](module-versions.html#list-module-versions) for the `ok` status. * `errored` - Module has been created, however its synchronization has failed. Attribute `error-message` contains the details.
      - `vcs-repo` object, nullable
        - `identifier` string, required: A reference to the module's VCS repository. For GitHub, GitHub Enterprise and GitLab the format is `<org>/<repo>`. Azure DevOps Services has the format `<org>/<project>/<repo>`.
        - `path` string: The repository sub-directory where the module source is located. If omitted or submitted as an empty string, this defaults to the repository's root.
        - `tag-prefix` string: Specify this attribute when a module's releases are namespaced within a repository's Git tags. This is usually the case for a mono repos with individually versioned components. For example if your module is tagged `my-module/v1.0.0` it's `tag_prefix` is `my-module/`.
    - `id` string
    - `links` object
      - `self` string
    - `relationships` object
      - `account` object: The relationship `account` is deprecated. Use `namespace` instead.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'accounts' | '', required
      - `created-by` object: The user who has created the module.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'users' | '', required
      - `docker-integration` object: Docker registry connection used by OCI-backed modules.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'docker-integrations' | '', required
      - `environment` object: The relationship `environment` is deprecated. Use `namespace` instead.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'environments' | '', required
      - `latest-module-version` object: The module's latest version.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'module-versions' | '', required
      - `module-version` object: The module's latest successful version.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'module-versions' | '', required
      - `module-versions` object: The IDs of the module versions.
        - `data` object[], nullable, required
          - `id` string, required
          - `type` 'module-versions' | '', required
      - `namespace` object: The module namespace this module belongs to.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'module-namespaces' | '', required
      - `vcs-provider` object: The module's VCS provider.
        - `data` object, nullable, required
          - `id` string, required
          - `type` 'vcs-providers' | '', required
    - `type` 'modules', required
  - `included` object[]
  - `meta` object

## Other responses

- `403`: User unauthorized to perform action.
- `404`: Relationship resource not found, or user unauthorized to perform action.
- `422`: Malformed request body (missing attributes, wrong types, etc.).
- `4XX`: Client error.
- `5XX`: Server error.

## Changes

- **2026-11-03** `d3e1dc85657a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/scalr/apis/scalr-iacp-api/changes/modules/post.md)

---

[API](https://skmtc.dev/scalr/apis/scalr-iacp-api.md) - [All operations](https://skmtc.dev/scalr/apis/scalr-iacp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scalr/apis/scalr-iacp-api/revisions/d3e1dc85657a?raw)