---
title: "Create one project file"
method: POST
path: "/v1/integration/projects/{projectId}/files"
tags: ["Unified Project Lifecycle APIs"]
---

# Create one project file

`POST /v1/integration/projects/{projectId}/files`

## Request

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

Creates one project file through the unified project API, for either an Advanced Replication (DSL) project or a Mainframe Replication pipeline.

**Features:**
- `content` is always a Base64-encoded string, regardless of `mimeType` (for example `application/yaml`, `application/x-yaml`, or `text/plain`) — this keeps binary-safe transport consistent for every file type and avoids JSON-escaping issues with raw file text.
- The response includes file metadata plus an `ETag` response header carrying a fingerprint hash of the created content; the same hash is also returned as `contentHash` in the body so callers that only inspect the JSON body (without reading headers) can still detect changes.
- Fails with a conflict when a file already exists at the requested path — use the update
endpoint instead, or move/rename the existing file first.
- For Mainframe Replication, pass the pipeline identifier via `pipelineId`; Advanced Replication ignores `pipelineId` and instead uses the project's working set plus optional `revisionNumber`.

**Use Cases:**
- VS Code extension creates a new DSL file within a project.
- User seeds initial project files during onboarding or scaffolds a new pipeline definition.

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

## Path parameters

- `projectId` string, required

## Query parameters

- `projectType` 'REPLICATION' | 'MAINFRAME_REPLICATION' | 'ADVANCED_REPLICATION', required: Supported project types for unified project operations
- `pipelineId` string
- `revisionNumber` integer

## Request body

- ProjectFileUpsertRequest: Request payload for creating or updating one project file
  - `fileId` string: Identifier of an existing file to update. Required for a batch-save item that updates a file; ignored by the single create endpoint, which always creates a new file.
  - `flattenedPath` string: Path of the file within the project's flattened file tree. Required when creating a new file — via the single create endpoint, or as a batch-save item without fileId. Not required when fileId identifies an existing file to update.
  - `content` string: Base64-encoded file content, decoded using the declared encoding
  - `mimeType` string: MIME type of the file content
  - `encoding` string: Encoding used to decode the Base64 content
  - `expectedVersion` integer: Expected current version, used for optimistic concurrency when overwriting
  - `expectedContentHash` string: Optional content-hash precondition, checked only when this item updates an existing file (fileId supplied). If it does not match the file's current stored hash, only this item fails; other items are unaffected. Ignored when creating a new file.

## Response `200`

File created successfully

- ProjectFileSummaryResponse: Project file metadata. Content is intentionally omitted.
  - `fileId` string: Unique identifier of the file
  - `dataFlowId` string: Advanced Replication dataflow identifier owning this file, when applicable
  - `fileName` string: File name derived from the flattened path
  - `flattenedPath` string: Path of the file within the project's flattened file tree
  - `version` integer: Current version number of the file
  - `phase` 'DRAFT' | 'APPROVED' | 'PENDING_DELETION': Lifecycle phase of the file
  - `mimeType` string: MIME type of the file content
  - `encoding` string: Encoding of the file content
  - `sizeBytes` integer: Size of the file content in bytes
  - `contentHash` string: Hash of the file content, used for change detection
  - `entryFile` boolean: Whether this file is the project's designated entry file
  - `unchanged` boolean: True when an update matched the stored file and no write was performed; omitted for read (list/get) and create/delete responses

## Other responses

- `400`: Bad Request — the resolved project type does not support files (DI-ADAPTER-PRF-0009)
- `401`: Unauthorized
- `403`: Forbidden — requires replication-pipeline::create when permission harmonization is enabled, or legacy replication-pipeline::manage otherwise
- `404`: Not Found — project does not exist (DI-ADAPTER-PRF-0001)
- `409`: Conflict — a file already exists at the requested path (DI-ADAPTER-PRF-0003), or the project has a commit in progress (DI-ADAPTER-PRF-0005)
- `500`: Internal Server Error — file creation failed (DI-ADAPTER-PRF-0002)

---

[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)