Feedback

List feedback entries

Example Request:

curl "https://controller-host:8001/api/v2/feedback" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "feedback": [
        {
            "feedbackId": "1",
            "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
            "username": "jsmith@example.com",
            "sourceText": "This is a sample input text.",
            "machineTranslation": "C'est un exemple de texte d'entrée.",
            "suggestedTranslation": "Ceci est un exemple de texte d'entrée.",
            "comment": "This is a sample feedback entry for documentation.",
            "approvalState": "awaitingApproval",
            "reviewer": "",
            "timestamps": {
                "reviewed": "",
                "created": "2021-05-25 00:14:01.363221018Z",
                "modified": "2021-05-25 00:14:01.363221018Z"
            }
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Return a list of feedback entries.

HTTP Request

GET /api/v2/feedback

Request Parameters

These parameters should be added to the URL as a query string.

Name	Type	Description	Default Value
languagePairId (optional)	string	Show only feedback with the given languagePairId. Cannot be used in combination with sourceLanguageId or targetLanguageId
sourceLanguageId (optional)	string	Show only feedback with the given sourceLanguageId
targetLanguageId (optional)	string	Show only feedback with the given targetLanguageId
username (optional)	string	Show only feedback created by the given user. This field is ignored for non-admin users
sourceText (optional)	string	Show only feedback when its source text contains the given sourceText
machineTranslation (optional)	string	Show only feedback when its machine translation contains the given machineTranslation
suggestedTranslation (optional)	string	Show only feedback when its suggested translation contains the given suggestedTranslation
comment (optional)	string	Show only feedback when its comment contains the given comment
approvalStates (optional)	string	Show only feedback with the given list of approvalStates, separated by commas (see list of valid approvalStates)
reviewer (optional)	string	Show only feedback reviewed by the given user
startTimeCreated (optional)	string	Show only feedback that were created on or after the given timestamp (see timestamps for formatting)
endTimeCreated (optional)	string	Show only feedback that were created on or before the given timestamp (see timestamps for formatting)
page (optional)	int	Page number to return	1
perPage (optional)	int	Number of feedback to return per page	25

Returns

Returns a list of feedback as a FeedbackList object with the following attributes:

Name	Type	Description
feedback	array of objects	List of feedback as an array of Feedback objects
page	int	Page number returned
perPage	int	Number of feedback returned per page
totalPages	int	Total number of pages available
totalItems	int	Total number of feedback

Create a feedback entry

Example Request:

curl "https://controller-host:8001/api/v2/feedback" \
	-X POST \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
	--data-urlencode machineTranslation="C'est un exemple de texte d'entrée." \
	--data-urlencode sourceText="This is a sample input text." \
	--data-urlencode suggestedTranslation="Ceci est un exemple de texte d'entrée."

Example Response:

{
    "feedbackId": "1",
    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "username": "jsmith@example.com",
    "sourceText": "This is a sample input text.",
    "machineTranslation": "C'est un exemple de texte d'entrée.",
    "suggestedTranslation": "Ceci est un exemple de texte d'entrée.",
    "comment": "This is a sample feedback entry for documentation.",
    "approvalState": "awaitingApproval",
    "reviewer": "",
    "timestamps": {
        "reviewed": "",
        "created": "2021-05-25 00:14:01.363221018Z",
        "modified": "2021-05-25 00:14:01.363221018Z"
    }
}

Create a feedback entry for the specific language pair, source text, and machine translation combination.

HTTP Request

POST /api/v2/feedback

Request Parameters

Name	Type	Description	Default Value
languagePairId	string	Identifier of the language pair
sourceText	string	Text that was originally submitted for translation
machineTranslation (optional)	string	Result of the translation of the source text
suggestedTranslation (optional)	string	Suggested improvement for the translation of the source text. It cannot be the same as the supplied machine translation
approvalState (optional)	string	Whether to approve or reject the feedback entry, only available for admin users. (see list of valid approval states)	awaitingApproval
comment (optional)	string	Notes to keep for this feedback entry

Returns

Returns the created feedback as a Feedback object with the following attributes:

Name	Type	Description
feedbackId	string	Identifier for the feedback entry
languagePairId	string	Identifier of language pair
username	string	Username of user who created translation job
sourceText	string	Text that was originally submitted for translation
machineTranslation	string	Result of the translation of the source text
suggestedTranslation	string	Suggested improvement for the translation of the source text
comment	string	Notes to keep for this feedback entry
approvalState	string	Whether the feedback entry has been approved or rejected. (see list of valid approval states)
reviewer	string	Username of the user who approved or rejected this feedback entry
timestamps	object	Timestamps of checkpoints in the life of the feedback
→ reviewed	string	When the feedback was approved or rejected (see timestamps for formatting)
→ created	string	When the feedback was created (see timestamps for formatting)
→ modified	string	When any part of the feedback was modified (see timestamps for formatting)

Approval States

Method	Description
awaitingApproval	feedback has not been reviewed by an admin user
approved	feedback has been reviewed and approved by an admin user
rejected	feedback has been reviewed and rejected by an admin user

Retrieve a feedback entry

Example Request:

curl "https://controller-host:8001/api/v2/feedback/1" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "feedbackId": "1",
    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "username": "jsmith@example.com",
    "sourceText": "This is a sample input text.",
    "machineTranslation": "C'est un exemple de texte d'entrée.",
    "suggestedTranslation": "Ceci est un exemple de texte d'entrée.",
    "comment": "This is a sample feedback entry for documentation.",
    "approvalState": "awaitingApproval",
    "reviewer": "",
    "timestamps": {
        "reviewed": "",
        "created": "2021-05-25 00:14:01.363221018Z",
        "modified": "2021-05-25 00:14:01.363221018Z"
    }
}

Return a feedback entry with the specific feedback ID.

HTTP Request

GET /api/v2/feedback/{feedbackId}

Path Parameters

Name	Type	Description
feedbackId	int	Feedback ID of the entry to return

Returns

Returns the specified feedback as a Feedback object.

Update a feedback entry

Example Request:

curl "https://controller-host:8001/api/v2/feedback/1" \
	-X PUT \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-d approvalState="approved" \
	--data-urlencode suggestedTranslation="Ceci est un exemple de texte d'entrée."

Example Response:

{
    "feedbackId": "1",
    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "username": "jsmith@example.com",
    "sourceText": "This is a sample input text.",
    "machineTranslation": "C'est un exemple de texte d'entrée.",
    "suggestedTranslation": "Ceci est un exemple de texte d'entrée.",
    "comment": "",
    "approvalState": "awaitingApproval",
    "reviewer": "jsmith@example.com",
    "timestamps": {
        "reviewed": "2021-05-25 03:14:01.363221018Z",
        "created": "2021-05-25 00:14:01.363221018Z",
        "modified": "2021-05-25 03:14:01.363221018Z"
    }
}

Update a feedback entry with the specific feedback ID.

HTTP Request

PUT /api/v2/feedback/{feedbackId}

Path Parameters

Name	Type	Description
feedbackId	int	Feedback ID of the entry to update

Request Parameters

Name	Type	Description	Default Value
suggestedTranslation (optional)	string	Suggested improvement for the translation of the source text. If an empty string is provided, the suggested translation in effect will be an empty string
approvalState (optional)	string	Whether to approve or reject the feedback entry, only available for admin users (see list of valid approvalStates)	awaitingApproval
comment (optional)	string	Notes to keep for this feedback entry. If an empty string is provided, the previous comment will be removed

Returns

Returns the updated feedback as a Feedback object.

Export feedback entries

Example Request:

curl "https://controller-host:8001/api/v2/feedback/export" \
	-X GET \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

<tmx version="1.4">
    <header creationtool="Language Weaver Edge" creationtoolversion="8.4.1" segtype="sentence" o-tmf="" adminlang="en-us" srclang="en" datatype="plaintext"></header>
    <body>
        <tu srclang="en">
            <tuv xml:lang="en">
                <seg>hello world</seg>
            </tuv>
            <tuv xml:lang="es">
                <seg>hola mundo</seg>
            </tuv>
            <tuv creationid="MT!" xml:lang="es">
                <seg>hola tierra</seg>
            </tuv>
            <note>example comment</note>
            <prop type="language_pair_id">EngSpa_Generic_SRV_TNMV_8_5_x_6</prop>
            <prop type="username">admin@localhost</prop>
            <prop type="approval_state">approved</prop>
            <prop type="reviewer">admin@localhost</prop>
            <prop type="review_date">2021-08-11 21:06:57.242039142Z</prop>
            <prop type="creation_date">2021-08-11 21:06:47.393801674Z</prop>
            <prop type="last_modification_date">2021-08-11 21:06:47.393801674Z</prop>
        </tu>
    </body>
</tmx>

Retrieve an export of feedback entries in TMX format.

HTTP Request

GET /api/v2/feedback/export

Request Parameters

These parameters should be added to the URL as a query string.

Name	Type	Description	Default Value
feedbackIds (optional)	string	List of feedback identifiers, separated by commas, to export
languagePairId (optional)	string	LP to export feedback for (if unspecified, feedback for all LPs will be exported). Cannot be used in combination with sourceLanguageId or targetLanguageId
sourceLanguageId (optional)	string	Identifier of source language to export feedback for
targetLanguageId (optional)	string	Identifier of target language to export feedback for
username (optional)		Export only feedback created by the given user. This field is ignored for non-admin users
sourceText (optional)	string	Export only feedback when its source text contains the given sourceText
machineTranslation (optional)	string	Export only feedback when its machine translation contains the given machineTranslation
suggestedTranslation (optional)	string	Export only feedback when its suggested translation contains the given suggestedTranslation
approvalStates (optional)	string	Export only feedback with the given list of approval states, separated by commas (see list of valid approvalStates)
reviewer (optional)	string	Export only feedback reviewed by the given user
startTimeCreated (optional)	string	Export only feedback that were created on or after the given timestamp (see timestamps for formatting)
endTimeCreated (optional)	string	Export only feedback that were created on or before the given timestamp (see timestamps for formatting)

Returns

Returns the TMX contents of feedback entries with MIME type text/x-tmx.

Import feedback entries

Example Request:

curl "https://controller-host:8001/api/v2/feedback/import" \
	-X POST \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-H "Content-Type: multipart/form-data" \
	-F file="@<file>"

Example Response:

{
    "successful": 10,
    "duplicate": 2,
    "invalid": 1,
    "warnings": [
        "no valid language pairs could be determined"
    ]
}

Import a file of feedback entries that is in TMX format.

HTTP Request

POST /api/v2/feedback/import

Request Parameters

Name	Type	Description	Default Value
applyAll (optional)	boolean	Apply all imported feedback entries to all installed language pairs that have the same matching source and target language	false
approveAll (optional)	boolean	Approve all imported feedback entries if no other feedback entry with matching language pair and source text has already been approved	false
file	file	File of feedback entries that is in TMX format

Returns

Returns the imported feedback as an ImportFeedbackResponse object with the following attributes:

Name	Type	Description
successful	int	The number of feedback entries that were imported
duplicate	int	The number of feedback entries that were not imported due to another existing feedback with matching language pair, source text, and suggested translation
invalid	int	The number of feedback entries that were not imported due to an error
warnings	array of strings	List of warnings encountered when importing invalid feedback (up to a maximum of 10 warnings listed)

Delete a feedback entry

Example Request:

curl "https://controller-host:8001/api/v2/feedback/1" \
	-X DELETE \
	-u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "feedbackId": "1",
    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "username": "jsmith@example.com",
    "sourceText": "This is a sample input text.",
    "machineTranslation": "C'est un exemple de texte d'entrée.",
    "suggestedTranslation": "Ceci est un exemple de texte d'entrée.",
    "comment": "",
    "approvalState": "rejected",
    "reviewer": "jsmith@example.com",
    "timestamps": {
        "reviewed": "2021-05-25 03:20:01.363221018Z",
        "created": "2021-05-25 00:14:01.363221018Z",
        "modified": "2021-05-25 03:20:01.363221018Z"
    }
}

Delete a feedback entry with the specific feedback ID.

HTTP Request

DELETE /api/v2/feedback/{feedbackId}

Path Parameters

Name	Type	Description
feedbackId	int	Feedback ID of the entry to delete

Returns

Returns the deleted feedback as a Feedback object.

Delete feedback entries

Example Request:

curl "https://controller-host:8001/api/v2/feedback/batch-delete" \
	-X DELETE \
	-u u_jsmith@example.com_u0VmztKJrwqf: \
	-d feedbackIds="1"

Example Response:

1

Delete feedback entries.

HTTP Request

DELETE /api/v2/feedback/batch-delete

Request Parameters

These parameters should be added to the URL as a query string.

Name	Type	Description	Default Value
feedbackIds (optional)	int	Comma separated identifiers of feedback entries to delete
languagePairId (optional)	string	Delete only feedback with the given languagePairId. Cannot be used in combination with sourceLanguageId or targetLanguageId
sourceLanguageId (optional)	string	Delete only feedback with the given sourceLanguageId
targetLanguageId (optional)	string	Delete only feedback with the given targetLanguageId
username (optional)	string	Delete only feedback created by the given user. This field is ignored for non-admin users
sourceText (optional)	string	Delete only feedback when its source text contains the given sourceText
machineTranslation (optional)	string	Delete only feedback when its machine translation contains the given machineTranslation
suggestedTranslation (optional)	string	Delete only feedback when its suggested translation contains the given suggestedTranslation
comment (optional)	string	Delete only feedback when its comment contains the given comment
approvalStates (optional)	string	Delete only feedback with the given list of approvalStates, separated by commas (see list of valid approvalStates)
reviewer (optional)	string	Delete only feedback reviewed by the given user
startTimeCreated (optional)	string	Delete only feedback that were created on or after the given timestamp (see timestamps for formatting)
endTimeCreated (optional)	string	Delete only feedback that were created on or before the given timestamp (see timestamps for formatting)

Returns

Returns the number of deleted feedback entries.