> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating artifacts with the Maia API

export const designer = "Designer";

export const maia = "Maia";

In {maia}, an [artifact](/docs/guides/artifacts) is an immutable collection of resources (such as data pipelines and script files) that is built as a compilation of executable assets and deployed to a specific environment on publication.

You can use the Maia API to interact with artifacts in the following ways:

* Create an artifact
* Promote an artifact to environments
* Disable an artifact

***

## Prerequisites

You can use the Python script provided below to streamline artifact creation. It handles the necessary configurations and file structuring, and automatically includes any custom or Flex connectors in your project. The script is optional unless your project uses custom or Flex connectors.

Download the script, requirements, and README here:

1. [publish.py](https://matillion-docs.s3.eu-west-1.amazonaws.com/Attachments/artifacts-cicd/publish.py)
2. [requirements.txt](https://matillion-docs.s3.eu-west-1.amazonaws.com/Attachments/artifacts-cicd/requirements.txt)
3. [README.md](https://matillion-docs.s3.eu-west-1.amazonaws.com/Attachments/artifacts-cicd/README.md)

Alternatively, you can [add connectors manually](#add-connectors-manually).

***

## Create an artifact

Follow these steps to create an artifact in your project using the API. This POST call with generate a deployable artifact within a specified environment.

`POST /v1/projects/{projectId}/artifacts`

* The request must be sent as `multipart/form-data`.
* Each file *must* be explicitly listed. The use of archive type files to create an artifact is not supported.
* If a pipeline (such as `example_pipeline`) exists within a folder (such as `example_folder`), then the key should follow this format: `example_folder/example_pipeline.orch.yaml`.

<Note>
  This request does not make any changes to the folder structure within your {maia} project. The file path you provide is how your pipeline will be referenced when it is executed. We recommend that the implied folder structure of your provided files matches the folder structure you are using in {designer} within the corresponding {maia} project. This helps to avoid path mismatches that may result in unexpected behavior.
</Note>

### Request headers

| Header            | Required | Description                                                                                                                                                                                               |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `versionName`     | Required | A unique version identifier for the artifact. Use a consistent naming convention such as semantic versioning (e.g. `1.0.0`). This value is used to reference the artifact when promoting or executing it. |
| `environmentName` | Required | The name of the environment to publish the artifact to (e.g. `Dev Environment`).                                                                                                                          |
| `commitHash`      | Optional | The Git commit hash associated with this artifact. Including this value links the artifact to a specific point in your version history, which is useful for traceability in CI/CD pipelines.              |
| `Authorization`   | Required | Your Bearer access token.                                                                                                                                                                                 |

### Request body

The request body must be sent as `multipart/form-data`. Unlike a standard JSON body, each file in your project is uploaded as a separate form field in the same request.

Each form field follows this format:

* **Key**: The relative file path (e.g. `example_folder/example_pipeline.orch.yaml`). This path is how the pipeline will be referenced during execution, so it should reflect the folder structure in your {maia} project.
* **Value**: The file to upload. In curl, prefix the path with `@` to reference a local file.

<Warning>
  If your project uses custom or Flex connectors, you must include them when creating an artifact via the API. The {maia} UI handles this automatically. With the API, you must include them—use the [publish.py script](#prerequisites) or [add them manually](#add-connectors-manually).
</Warning>

### Example request - create artifact

```sh theme={null}
curl --location 'https://eu1.api.matillion.com/dpc/v1/projects/{projectId}/artifacts' \
--header 'versionName: 1.0.0' \
--header 'environmentName: {environmentName}' \
--header 'commitHash: {gitCommitHash}' \
--header 'Authorization: Bearer {accessToken}' \
--form 'example_folder/example_pipeline.orch.yaml=@"/Users/my-username/workspace/dpc-demo/example_folder/example_pipeline.orch.yaml"' \
--form 'example_folder/hello-world.py=@"/Users/my-username/workspace/dpc-demo/example_folder/hello-world.py"'
```

Replace `{projectId}`, `{environmentName}`, `{gitCommitHash}`, and `{accessToken}` with the appropriate values.

***

## Promote artifacts between environments

Once an artifact is created, it can be promoted (deployed) to other environments.

`POST /v1/projects/{projectId}/artifacts/promotions`

You'll need to obtain the artifact `versionName` using the following GET call: `/v1/projects/{projectId}/artifacts/`.

Once you have the artifact `versionName`, you can use the API to promote the artifact.

### Example request - promote artifact

```sh theme={null}
curl --location 'https://eu1.api.matillion.com/dpc/v1/projects/{projectId}/artifacts/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "sourceEnvironmentName": "{your-source-environment}",
    "targetEnvironmentName": "{your-target-environment}",
    "versionName": "{value}"
}'
```

Replace `{projectId}`, `{your-source-environment}`, `{your-target-environment}`, and the `{value}` of `versionName` with the appropriate values.

***

## Disable an artifact

If an artifact is no longer required, it can be disabled. A disabled artifact cannot be executed and will not appear as an available artifact by default.

`PATCH /v1/projects/{projectId}/artifacts/`

### Example request - disable artifact

```sh theme={null}
curl --location --globoff --request PATCH 'https://eu1.api.matillion.com/dpc/v1/projects/{projectId}/artifacts' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "environmentName": "{your-environment}",
  "versionName": "{value}",
  "enabled": false
}'
```

Replace `{projectId}`, `{your-environment}`, and the `{value}` of `versionName` with the appropriate values.

***

## Add connectors manually

You can manually retrieve and incorporate connectors. First, you'll need to use the following endpoints to get your connector objects.

* **Custom connectors:** `GET /v1/custom-connectors`
* **Flex connectors:** `GET /v1/flex-connectors`

Each API call returns a JSON array containing multiple connector objects. Iterate through the array and save each object as a separate file in the root directory of your repository.

### Naming convention for connectors

Each file should be named as follows:

`connector-profile:custom-{id}.json`

Example:

`connector-profile:custom-77e6b173-24f5-4bfd-9f8f-787dbdd74c6a.json`

### Naming convention for flex connectors

`connector-profile:flex-{id}.json`

Example:

`connector-profile:flex-datadog.json`

<Warning>
  Do not add these files to your Git repository if the repository is linked to your {maia} project.
</Warning>