Requests and responses

Use the endpoint reference to confirm supported parameters. The patterns below apply to the repository and model list endpoints used in this guide; specialized endpoints can return different shapes or support fewer options.

Base URL and identifiers#

The base URL includes the application context and API version:

Text

https://your-server.example/mt-backend/api/v1

Append an endpoint path, for example /repositories/{repositoryId}/models. Repository and model identifiers are UUIDs returned as uuid. Document keys and other provider-specific identifiers are not necessarily UUIDs. Preserve the values returned by the API and URL-encode path or query values when necessary.

More detail: draft paths and provider-property exceptions

Endpoint-specific identifier exceptions#

Draft operations are an exception: POST /repositories/draft/models creates a draft model in the dedicated draft repository. The draft segment is case-insensitive. Draft acceptance also allows draft in place of repositoryId; other repository operations require the documented UUID.

Path parameters use descriptive names such as repositoryId and modelId; response fields retain names such as uuid. A versionNumber is an integer, while a property providerId and document sourceId identify providers rather than repository resources.

User-property endpoints currently have two limitations: listing requires a provider segment but does not filter by it, and updating/deleting a property requires a UUID-formatted key even though reading and creating properties accept string keys. Vertex-property endpoints also currently require a UUID-formatted provider identifier. Check the endpoint description before using those operations.

Pagination#

List responses commonly include:

Field	Meaning
`startAt`	Zero-based result offset for this page
`maxResults`	Requested page size; the final page can contain fewer items
`total`	Total matching resource count, not just this page's count
`data`	The resources returned on this page

Start with startAt=0&maxResults=50. Process the returned data, then advance by the number of returned items. Stop when data is empty or the next offset reaches total. Use a positive page size.

HTTP request

GET /mt-backend/api/v1/repositories?startAt=0&maxResults=50
GET /mt-backend/api/v1/repositories?startAt=50&maxResults=50

Repository/model list requests default to offset 0 and page size 10. Offset pagination is not a snapshot: concurrent additions or removals can change the result set while you read it.

Select fields and projections#

A projection is an endpoint-defined set of response fields. The reference lists the projections supported by each operation. Query-resource endpoints support DEFAULT and ALL; SIMPLE is available only when that resource defines a compact representation. For example, Color schemes supports DEFAULT and ALL, while repositories also support SIMPLE.

No explicit projection uses DEFAULT.
SIMPLE returns a compact representation. For repositories it contains uuid and name; for models it contains uuid and modelType.
fields requests a comma-separated set of fields. Combined with a projection, the selection includes both sets; it does not subtract fields from the projection.

For model titles alongside a compact response:

HTTP request

GET /mt-backend/api/v1/repositories/{repositoryId}/models?projection=SIMPLE&fields=titles

Avoid fetching ALL automatically for large lists. Request the information your integration needs.

More detail: selection paths and description fields

How selection paths differ from response keys#

The fields description lists the selection paths for that endpoint. These are request paths, which can differ from keys in the response: an association may be flattened or transformed into a localized map. For models, select titles; do not assume that titles.title, which is a supported sort path, is also a valid selection path. Field access can require additional privileges.

Description endpoints use a separate selection contract: fields=descriptionType,content, with case-sensitive names and no projection parameter. Omitting fields includes both fields.

Filter and sort#

Use filter for text matching and filterFields to choose the text fields to search. Without filterFields, text filtering uses the selected fields. An asterisk is a wildcard; URL-encode query values rather than concatenating user input into a URL.

This request searches repository names containing "Process" and sorts them by name:

Bash / cURL

curl --fail-with-body --silent --show-error --get \
  --header "x-api-key: $API_KEY" \
  --data-urlencode 'projection=SIMPLE' \
  --data-urlencode 'filter=*Process*' \
  --data-urlencode 'filterFields=name' \
  --data-urlencode 'sortBy=name' \
  --data-urlencode 'ascending=true' \
  "$API_BASE_URL/repositories"

Use ascending=false for descending order.

More detail: supported paths and localized sorting

Sort localized titles#

Each endpoint's filterFields and sortBy descriptions list its supported paths. These lists are separate: text filtering can search an association, while sorting needs a scalar value. Ordinary query resources match stored text before response transformations; compound model queries match transformed values, including non-string scalar values as text.

For model titles, sortBy=titles.title sorts using the repository's default language unless you supply sortLanguage as one language UUID belonging to that repository. Vertex titles use sortBy=symbol.titles.title. A collection sort needs a qualifier to identify one value per item; use the documented localized sort paths, rather than an arbitrary collection field. Do not send sortLanguage with an unrelated sort path.

Some DTO-based lists implement pagination only, without filtering or sorting; their reference omits those unused controls. Leave optional inputs without defaults blank. The downloaded OpenAPI includes a projection enum and x-2c8-supported-values lists for field/filter/sort discovery. Field lists remain comma-separated strings on the wire, not arrays or enums of complete combinations.

Localized content#

Retrieve the repository's language definitions:

Bash / cURL

curl --fail-with-body --silent --show-error \
  --header "x-api-key: $API_KEY" \
  "$API_BASE_URL/repositories/$REPOSITORY_ID/languages?startAt=0&maxResults=50"

Entries identify languages by uuid and mark the default with defaultLanguage. Use these UUIDs to interpret keys in title and description maps. Paginate this list if necessary.

Additional-language values can carry translated; default-language values may omit it. Missing or untranslated content needs an explicit display choice in your integration, such as falling back to the default language. The flag is not an instruction to translate text automatically.

Language filtering and localized writes differ between endpoints. Consult the schema rather than adding language or translated indiscriminately.

Reference: Languages.

Success responses#

Operation	Common response
Read a resource	`200` with a resource object
Read a resource list	`200` with a paginated envelope
Create a resource	`201`; inspect the endpoint for its body and headers
Update a resource	Often `200`; inspect the endpoint's response
Delete a resource	Often `204`, with no body to parse

These are common patterns, not a universal response contract. For example, canvas responses are objects, and document-source APIs can return arrays without pagination. Check the status and content type before parsing a response.

Handle failures using Troubleshooting and support.