Skip to main content
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 if you don’t.

​
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:
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

​
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).

​
Not the standalone Connectors API

The same product-boundary confusion that applies to connector lifecycle applies here too: the standalone Connectors API 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

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.
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.

​
Key concepts

​
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 if you don’t have one set up yet.

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

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.
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.
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.

​
3. Browse the remote folder: don’t ask for a path

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/....
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.
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:
This is a full replace: it requires frequency, id, monitoredFolders, and name in the body regardless of what you’re actually changing.
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.
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), 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

Managing TMS Connectors

Create and configure the connector an APC setting runs on.

Connectors API

Move file content through a connector that’s already set up.