---
title: "Create a DSL file"
method: POST
path: "/v1/integration/advanced-dsl/projects/{projectId}/files"
tags: ["Advanced DSL Project Management"]
---

# Create a DSL file

`POST /v1/integration/advanced-dsl/projects/{projectId}/files`

## Request

- Base URL: `https://integration-adapter.connect.cloud.precisely.com`
- URL: `https://integration-adapter.connect.cloud.precisely.com/v1/integration/advanced-dsl/projects/{projectId}/files`
- Auth: HTTP bearer

Creates a new DSL file asset in the project using multipart/form-data upload.

**Features**
- Creates a brand-new file asset in the catalog.
- Initializes file version to `1` for all newly created files.
- Persists content, hash, size, MIME type, encoding, and phase metadata.
- Links the file to the selected revision via `Includes` relationship.
- When `revisionNumber` is omitted, links against the latest project revision.

**Use Cases**
- Adding a newly authored DSL file to a project.
- Creating a file before first inclusion in a revision.
- Programmatic project bootstrap with initial file assets.

**Scenarios**
- New file create + explicit revisionNumber → file is created and linked to that revision.
- New file create + no revisionNumber → file is created and linked to latest revision.
- File created but already linked to target revision → no duplicate relationship is created.

**Required Permissions**: `replication-pipeline::create` when permission harmonization is enabled; otherwise, `replication-pipeline::manage`.

## Path parameters

- `projectId` string, required

## Query parameters

- `mimeType` string
- `encoding` string
- `phase` string
- `flattenedPath` string
- `revisionNumber` integer

## Response `201`

File created successfully

- SaveDslFileResponse: Response confirming the DSL file was saved successfully
  - `fileId` string: Catalog asset ID of the saved file
  - `name` string: The base name of the saved file
  - `flattenedPath` string: The flattened path of the saved file
  - `phase` string: The current lifecycle phase of the file after save
  - `version` integer: The version of the file after save
  - `timestamp` string, date-time: Server timestamp when the save was processed

## Other responses

- `400`: Invalid request — missing file part, unreadable content, or constraint violation
- `401`: Missing or invalid authentication token
- `403`: Insufficient permissions — requires `replication-pipeline::create` or legacy `replication-pipeline::manage`
- `404`: Project or selected revision not found
- `500`: Internal server error — catalog asset create, relationship create, or retrieval failed (error codes: DI-ADAPTER-DSL-0020 DSL_FILE_SAVE_FAILED)

---

[API](https://skmtc.dev/precisely/apis/precisely-integration-adapter-service.md) · [All operations](https://skmtc.dev/precisely/apis/precisely-integration-adapter-service/llms.txt) · [OpenAPI document](https://skmtc.dev/precisely/apis/precisely-integration-adapter-service/revisions/2d2629f4987d?raw)