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

# Managing Automated Project Creation

> Set up, create, and troubleshoot Automated Project Creation (APC), the Phrase TMS feature that turns a connector into a scheduled or webhook-triggered pipeline for creating translation projects.

<Info>This guide is about **Automated Project Creation (APC)**, a Phrase Translation Management System (TMS) feature that watches a connector's remote storage and automatically creates translation projects when new files show up. It assumes you already have a working connector; see [Managing TMS Connectors](/en/guides/managing-connectors/overview) if you don't.</Info>

## Quickstart

Before building a full setting, confirm your token can reach the Automated Project Creation endpoints. This call lists the APC settings your organization already has and needs nothing beyond authentication:

```bash theme={null}
GET /api2/v1/automatedProjects
```

A `200` response with a page of results (even an empty one) confirms you are connected and authorized. If it fails, fix authentication before going any further.

## Prerequisites

| Requirement           | How to get it                                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Authentication set up | See [Platform authentication](/en/api/platform/authentication).                                                          |
| A working connector   | APC always runs on top of an existing connector. See [Managing TMS Connectors](/en/guides/managing-connectors/overview). |

## What APC does

Automated Project Creation lets an already-configured connector do more than move files on request. It watches one or more folders (or, for connector types without a real filesystem, the equivalent browsable structure) on a schedule, and automatically creates a new translation project (or updates an existing continuous one) whenever it finds new or changed content.

APC always belongs to exactly one connector. There is no such thing as an APC setting that isn't tied to a connector; if you don't have one set up yet, create it first (see [Managing TMS Connectors](/en/guides/managing-connectors/overview)).

### Not the standalone Connectors API

The same product-boundary confusion that applies to connector lifecycle applies here too: the standalone [Connectors API](/en/api/connectors/introduction) only moves file content through an already-configured connector, and it has no concept of automated project creation. APC lifecycle lives entirely on the TMS API.

### The APC lifecycle endpoints

| Method & path                                                                | Purpose                                                                                                                     |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `GET /api2/v1/automatedProjects`                                             | List your APC settings (paginated; see [Listing is paginated](#listing-is-paginated))                                       |
| `POST /api2/v3/automatedProjects`                                            | Create an APC setting (see [Creating an APC](#creating-an-apc))                                                             |
| `GET /api2/v3/automatedProjects/{settingsId}`                                | View an APC setting's full configuration                                                                                    |
| `PUT /api2/v3/automatedProjects/{settingsId}`                                | Update an APC setting (full replace; see [The full-replace PUT](#the-full-replace-put-is-the-only-way-to-change-a-setting)) |
| `DELETE /api2/v1/automatedProjects/{settingsId}`                             | Delete one APC setting                                                                                                      |
| `DELETE /api2/v1/automatedProjects/batch`                                    | Delete several APC settings by id in one call                                                                               |
| `GET /api2/v1/automatedProjects/{settingsId}/running`                        | Check whether it's currently running                                                                                        |
| `GET /api2/v1/automatedProjects/{settingsId}/status`                         | Check its last-run status                                                                                                   |
| `GET .../monitoredFolder/{folder}/connectors/{connectorId}/folders/{folder}` | Browse an existing APC's monitored folder contents                                                                          |

<Tip>APC settings are organization-scoped. They're addressed directly by their own `settingsId`, never nested under a project, so don't construct a project-nested path for them.</Tip>

<Note>`GET /api2/v1/automatedProjects` returns up to 50 results per call (`pageSize`, 0-indexed `pageNumber`). Check `totalElements`/`totalPages` on the first response and page through all of them before treating the result as complete. A large organization can easily have well over 50 APC settings.</Note>

## Key concepts

| Term               | Definition                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Connector          | A configured link between Phrase TMS and a third-party system's storage, such as Google Drive, GitHub, or Phrase Strings. |
| Project template   | A reusable configuration used to create projects with standard settings, a source language, and target languages.         |
| Monitored folder   | A remote folder (or equivalent browsable location) that APC watches for new or changed content.                           |
| Continuous project | A single project that APC keeps updating on each run, instead of creating a new project every time.                       |
| Workflow step      | An ordered stage (for example translation or review) that a job moves through inside a project.                           |

## Creating an APC

Creating an APC setting has more required fields than a typical create call, and several of them have a real, discoverable set of valid options. Don't ask for these blind, and don't guess a shape for the ones with no dedicated list endpoint either.

### 1. Confirm the connector

Every APC belongs to an existing connector. List your connectors (`GET /api2/v1/connectors`) and confirm the one to use before anything else; never guess or fabricate a connector identifier. See [Managing TMS Connectors](/en/guides/managing-connectors/overview) if you don't have one set up yet.

### 2. Pick a project template: before languages, not after

```bash theme={null}
GET /api2/v1/projectTemplates
```

Lists your available templates by name and `uid`. Resolve this **before** asking about languages: a project template's detail response carries the source and target languages it was created with.

```bash theme={null}
GET /api2/v1/projectTemplates/{projectTemplateUid}
```

`sourceLang` and `targetLangs` on this response are inherited from the project the template was originally created from. This is exactly why the TMS UI only shows you language options once you've picked a template. Present those as your language choices, and only fall back to the full, unscoped `GET /api2/v1/languages` list if the chosen template happens to have no languages set.

<Tip>The resolved target languages go into the create payload's `selectedTargetLangs` field (a required array of language codes). The field name doesn't otherwise appear anywhere in this resolution step, so don't guess a different name (for example `targetLangs`) when building the request.</Tip>

### 3. Browse the remote folder: don't ask for a path

```bash theme={null}
GET /api2/v1/connectors/{connectorId}/folders
GET /api2/v1/connectors/{connectorId}/folders/{encodedFolder}
```

Lists the connector's root folders, or a subfolder if you pass one. Browse and present the real folders and projects found. Don't ask the user to type a path from memory, and don't guess a template like `/project/{id}` or `/space/...`.

<Note>For a `PHRASE`-type connector (TMS to Phrase Strings), the browsable structure returned here is Strings projects and spaces rather than a literal filesystem path, so present the real project and space names the endpoint returns. `PHRASE` is a real, valid connector type; if a browse call fails for a specific connector, that's an operation-specific failure, not evidence the connector or its type doesn't exist. See [`PHRASE` connectors are a valid, real connector type](#phrase-connectors-are-a-valid-real-connector-type).</Note>

Once a folder is chosen, translate it into the create payload's `monitoredFolders[]` entry: `remoteFolder` (the folder path), `folderNames` (its path segments as a list), and `humanReadableFolderPath`. Derive these from the browsed result; don't fabricate them from the folder name alone. `monitoredFolders[].localToken` is the connector's own `localToken` field (from its list or get response, not its `id`), which the backend needs to resolve which remote storage to read.

If a connector type doesn't support folder browsing at all, say so and let the user pick the folder in the TMS UI instead, then continue the rest of the flow normally.

### 4. Schedule (`frequency.frequencyOption`) or webhook trigger (`webhookToken`)

The schema requires **either** `frequency` **or** `webhookToken`, not both. Ask the user which triggering model they want before assuming a schedule is the only option.

For a schedule, there's no list endpoint (it's a genuine question), but the valid `frequencyOption` values come straight from the create endpoint's schema, so offer them as named options rather than an open "how often?":

* `WEEKLY_FIXED_TIMES`: runs at specific times on specific days of the week
* `HOUR_TIME_RANGE`: runs every N hours (`range`)
* `MINUTE_TIME_RANGE`: runs every N minutes (`range`)
* `MONTHLY_FIXED_TIMES`: runs at specific times on specific days of the month

Each option has its own sub-fields (for example `weeklyFixedTimes[]`, `monthlyFixedTimes[]`); check the full request schema for the shape once you know which one applies.

For a webhook-triggered setup instead, `webhookToken` is a plain string field: the automated project creation runs when that webhook is called, rather than on a schedule.

### 5. Translation-export rule

At least one `translationExports[]` entry is required. Again, there's no list endpoint, but the schema constrains the valid values:

* `exportFrom.type`: `FINAL_WORKFLOW_STEP` or `WORKFLOW_STEP` (with `workflowStep` number, if the latter)
* `exportWhen.exportTrigger`: `SELECTED_WORKFLOW_STEP_COMPLETED`, `FINAL_WORKFLOW_STEP_COMPLETED`, or `PROJECT_COMPLETED`

A reasonable default to suggest is exporting when the final workflow step completes, but present the actual options rather than assuming silently, and don't invent a webhook-based trigger; it isn't part of this schema.

### 6. Continuous vs. one-off projects

`continuousProject: true` imports files into a single, continuously-updated project instead of creating a new project on every run. This is a yes/no the user needs to decide; there's no discoverable default.

### Putting it together

Resolve every field above (connector, template and its languages, folder, schedule, export rule) before presenting a single confirmation message with real values for all of them. Don't send the user a list of field names to fill in one at a time, and don't offer to fetch a list "if you'd like"; fetch it, then ask.

## Troubleshooting

### The full-replace PUT is the only way to change a setting

There is no dedicated enable/disable or partial-update endpoint for APC. `GET .../running` and `GET .../status` are read-only state checks; they can't be used to change anything.

The **only** write path for any change, including just flipping `active`, is:

```bash theme={null}
PUT /api2/v3/automatedProjects/{settingsId}
```

This is a **full replace**: it requires `frequency`, `id`, `monitoredFolders`, and `name` in the body regardless of what you're actually changing.

<Warning>Sending a body with only the field you're changing (for example just `{"active": true}`) can be accepted by the API without an error, but doesn't actually persist the change. A follow-up `GET` will show the setting reverted to its previous state. The response echoing back your intended value is **not** proof the change was saved.</Warning>

To make any change safely:

1. `GET /api2/v3/automatedProjects/{settingsId}` first, **not** the `GET /api2/v1/automatedProjects` list result, which is a flatter shape (`connectorId`/`connectorName` instead of nested `monitoredFolders`) and is missing fields the `v3` `PUT` requires.
2. Take that full object, change only the field(s) you actually want to change, and send the **complete** object back.
3. `GET` the same `settingsId` again afterward and confirm the field actually changed before considering the update successful.

### Listing has no owner/creator field

Neither the list nor the single-get response for an APC setting exposes who created it. There's no way to filter "my APC settings," either server-side or by post-processing the response, since the field simply isn't there. If you need to narrow a large list down, filter by connector, by active or inactive state, or by name instead.

### Listing is paginated

`GET /api2/v1/automatedProjects` returns at most 50 results per call (`pageSize`, default and max 50; `pageNumber`, 0-indexed). Check `totalElements`/`totalPages` on the first response and keep paging until you've collected everything. Reporting the first page's contents as "the full list" is wrong the moment your organization has more than 50 APC settings.

### `PHRASE` connectors are a valid, real connector type

`PHRASE` (the connector that connects TMS to Phrase Strings) is a documented `ConnectorType` enum value, same as `BOX`, `GIT`, `CONTENTFUL`, `MARKETO`, or `OPTIMIZELY`. It's a legitimate choice for an APC's underlying connector. If browsing its folders behaves differently than a filesystem-backed connector (see [Browse the remote folder](#3-browse-the-remote-folder-dont-ask-for-a-path)), that's a property of that connector type, not a sign it doesn't exist or isn't supported.

### Deletion

`DELETE /api2/v1/automatedProjects/{settingsId}` deletes one setting; `DELETE /api2/v1/automatedProjects/batch` deletes several by id in a single call. Both are permanent, so confirm the exact setting(s) before calling either.

## Next steps

<CardGroup cols={2}>
  <Card title="Managing TMS Connectors" icon="plug" href="/en/guides/managing-connectors/overview">
    Create and configure the connector an APC setting runs on.
  </Card>

  <Card title="Connectors API" icon="folder-tree" href="/en/api/connectors/introduction">
    Move file content through a connector that's already set up.
  </Card>
</CardGroup>