The scope object. It delimits the total range of segments and related resources that can be queried.

Example:

"scope": { "type": "Project", "projectid": 1234 }

The filters to apply. See chapters further down.

Get segments in scope with a word in English and where the German translation has green status. Further, we want the segment context to be a "Heading" (we suppose we translate a Microsoft Word document).

"query": {
	"ctx": { "value": "Heading", "mode": "Prefix" },
	"languages": [
    	{ "locs": ["en"], "text": { "value": "ministry" } },
    	{ "locs": ["de"], "status": { 1 } }
	]
}

If layout is not set, the system creates one depending on the values of this property:

• "Languages" or null/missing: System returns columns for all languages in the languages node
• "Default": System fetches a default layout for the scope and the user.
• Null or missing: The layout is preset for the languages you specify in query.languages, see below:

This example returns results in 3 languages. Not setting the layoutMode requires explicitly specifying languages:

{
	"scope": {
		"type": "Job",
		"jobid": 16682,
		"jobcdyt": true
	},
	"query": {
		"languages": [    	
			{ "locs": ["en"] },
    		{ "locs": ["de"] },
			{ "locs": ["fr"] }
		]
	}
}

Alternatively, this can be written more compactly:

...
"query": {
	"languages": [
    	{ "locs": ["en", "de", "fr"] }
	]
}
...

Optional, default is 20. Specifies the number of segments to retrieve.

Optional. Default is "Natural". Specifies how results shall be sorted:

• Natural: The recommended value. It applies the Document order with jobs and projects and by date of creation with other scopes.
• SegmentId: Sort by creation date with most recent on top. The segment id is an auto-incremented unique number. This is the sort option that performs best.
• Document: Sort by resource, then document, then sequential segment number. Use with job and project scopes only.
• Text: Sort alphabetically in the first language specified in the languages property.
• TextLength: Sort by text length, shortest on top, in the first language specified in the languages property.
• Comments: Sort by comments. This is a special mode that requires the comments property be set. Used when you are basically interested in comments.

Example:

"sort": "Natural"

Optional sort direction. Options are:

• null / missing: Applies the most natural or logical direction for the selected sort.
• asc: Ascending
• desc: Descending

Example:

"sortdir": "desc"

Default sort orders:

• Natural: For job/project scopes uses "asc" (in the order of the document) otherwise "desc" (most recent segments on top)
• SegmentId: "desc", most recent segments on top
• Text: "asc", alphabetical order
• TextLength: "asc", shortest texts on top

Navigate to segment by segment ID

Specify mode and segment ID as shown below.

"goto": {
	"mode": "SegmentId",
	"sid": 2991
}

Navigate to segment by sequential ID

Segments of documents are assigned a sequential ID such as 1, 2, 3-1, 3-2 etc.

The first part is the bee segment ID (bsid), the second part is the sub segment ID (bssid).

"goto": {
	"mode": "BeeSegmentId",
	"bsid": 10,
    "bssid": 0
}

The bssid is optional. 0 denotes the first sub segment, 1 the second. In the user interfaces we display this number incremented by 1 (after all "3-1" looks better than "3-0"

NOTE: This mode is available only with Job or Project scopes.

Navigate to locked text

Navigates to the next (next: true) or previous (next:false) locked text relative to the specified segment ID.

"goto": {
	"mode": "LockedYes",
	"sid": 88721,
	"locale": "fr",
    "next": "true"
}

The locale parameter is mandatory.

Navigate to non-locked text

Navigates to the very first unlocked segment. Here we drop the sid value and thus navigate from the start.

"goto": {
	"mode": "LockedNo",
	"locale": "fr",
    "next": "true"
}

The locale parameter is mandatory.

Optional list of resources to search. A resource can be a translation memory, a term base or a project memory. See resources/documentsets to find resources and their IDs (dsid).

Example:

"documentSets": [ 1292, 19923 ]

Optional list of documents to search. With projects, a document is, well, a document being translated. With resources it groups segments added to a resource together. See resources/documents/list (post) to find documents and their IDs (did)

Each element is an object with these properties:

• did: The document ID
• minbsid, maxbsid: Optional (int?). Defines an optional range of the sequential segment ID in the document. The first segment in a document has number 1.
• minbssid, maxbssid: Optional (int?). Defines an optional range of the sub-segment numbers starting at 0. If a segment is split into sub-segments, all the sub-segments share the same bsid but have a different bssid.

Example:

"documents": [ { "did": 77362 } ]

Optional list of segments to search. The segment ID is the sid property included with search results.

Example:

"segments": [ 992821, 992822 ]

Optional filter on the type of resource to search:. Options are:

• 1: To search documents of a project (aka project memories)
• 2: To search translation memories
• 3: To search terminology databases

Example to search resources only while excluding any documents:

"resourceTypes": [ 2, 3 ]

Optional filter for segment-level custom fields.

A array of custom field filters. Each element filters one custom field value:

• id: The numeric ID of the custom field. Custom fields have IDs starting at 1. Mandatory.
• val: The value to find. Mandatory
• mode: The search mode. Uses "Plain" if not specified. Optional (See text.mode)
  Note: The search is an exact search for pick list custom fields, you can choose the mode for other field types.

• phrase: Optional phrase match flag. Default is false.

Example to find values prefixed with "Department" in custom text field #1:

"cfs": [ { "id": 1, "val": "Department.*", mode: "Regex" }, { "id": 5, "val": "Priority", "phrase": true } ]

When specifying multiple items, all of them must match.

Optional filter for segment-level labels.

A array of label filters. Each element filters one label value:

• id: The numeric ID of the label. Labels have IDs starting at 1. Mandatory.
• val:
  • The numeric label option to find. Use 0 for the first value option, 1 for the second, etc.
  • Use null to find segments where the label is not set. With labels configured to be always visible, a null-query is equivalent to finding the default value of the label. 

Example:

"lbls": [ { "id": 1, "val": 0 }, { "id": 23, "val": 3 }, { "id": 10, "val": null } ]

When specifying multiple items, all of them must match.

Optional filter on term-level TBX fields. An array of TBX field and value pairs. Each array element has these properties:

• id: TheTBX field ID. Mandatory.
• val: The value to find.
• mode: Optional search mode. Any of "Plain" (default, prefix search), "Wildcards", "Regex" or "Empty"
• phrase: Optional phrase match flag. Default is false.

Example:

"tbx": [ { "id": "context", "val": "Mechanical" }, { "id": "example", "val": "stru*e", "mode": "Wildcards" } ]

Optional array of languages and filters to apply. This permits to find source texts or translations by a wide range of filter criteria.

See table below for object properties.

Example: Find all source texts containing word "ministry" and where the German translation if flagged as erroneous.

{ 
	"query": {
		"languages": [
    		{ "locs": ["en"], "text": { "value": "ministry" } },
    		{ "locs": ["de"], "status": { "Red" } }
		]
	}
}

An array with one or more language codes. With multiple languages, filters apply to either one of the languages (a boolean "OR"). Let us look at an example:

Example 1: Search segments that contain "ministry" in any of the 3 languages:

{ 
	"query": {
		"languages": [
    		{ "locs": ["en", "de", "fr"], "text": { "value": "ministry" } }
		]
	}
}

Example 2: Search segments that contain "ministry" in all of the 3 languages:

{ 
	"query": {
		"languages": [
    		{ "locs": ["en"], "text": { "value": "ministry" } },
			{ "locs": ["de"], "text": { "value": "ministry" } },
			{ "locs": ["fr"], "text": { "value": "ministry" } }
		]
	}
}

The string to search.

Find any translation containing a word, case insensitive:

"text": { "value": "ministry of energy" }

Find all texts starting with:

"text": { "value": "Chapter*", "mode": "Wildcards", "case": false, "phrase": true }

Filter by status. An optional list of one or more statuses. See Text Status (Enumeration)

• 0: Neutral status
• 1: Green status ("OK")
• 2: Red status ("Problem")

Example:

"status": [ 2 ]

Filter by bookmark. An optional list of one or more bookmarks. See Text Bookmark (Enumeration)

• 0: No bookmark set
• 1: Blue bookmark
• 2: Red bookmark

Example:

"bookmarks": [ 1, 2 ]

Filter on the last text change date. This is an optional object.

See Date filter (Filter) for details.

Examples:

Periods are accumulated. The following finds texts changed the last 3 days:

"dttext": { "hours": 48, "days": 1 }

Find changes of October (UTC):

"dttext": { "min": "2018-10-1T00:00:00Z", "max": "2018-11-1T00:00:00Z" }

Filter on the last status or bookmark change. This is an optional object. The properties are the same as for dttext.

Example for finding any texts changed on or after a date:

"dtflags": { "min": "2018-10-26T10:40:00Z" }

Filter on the text length. The following finds all texts between 10 and 20 characters:

"lengthMin": 10,
"lengthMax": 20

Find texts with maximum of 10 characters:

"lengthMax": 10

Filter texts that are explicitly locked or unlocked for editing.

• True: Only locked texts.
• False: Only unlocked texts.

Example to find locked texts:

"locked": true

Filter texts by who is responsible for the latest version. See available options here: Last Editor (Enumeration).

Find all types of pre-translations:

"editors": [ 2, 3, 6, 7, 8, 9 ]

Find texts last edited by a human:

"editors": [ 1 ]

Filter texts by who has edited a past version of the text. See available options here: Last Editor (Enumeration).

Find any text that was initially a machine translation:

"pastEditors": [ 5 ]

Filter texts that were last edited by specific users.

"users": [ 100, 110 ]

Optional filter for language-level custom fields.

A array of custom field filters. Each element filters one custom field value:

• id: The numeric ID of the custom field. Custom fields have IDs starting at 1. Mandatory.
• val: The value to find. Mandatory.
  Note: The search is an exact search for pick list custom fields and a prefix search for all other custom field types. Mandatory.
• mode: Optional search mode. Any of "Plain" (default, prefix search), "Wildcards", "Regex" or "Empty"
• phrase: Optional phrase match flag. Default is false.

Example to find values prefixed with "Department A" in custom field #1:

"cfs": [ { "id": 1, "val": "Department A" }, { "id": 5, "val": "Priority" } ]

When specifying multiple items, all of them must match.

Optional filter for language-level labels.

A array of label filters. Each element filters one label value:

• id: The numeric ID of the label. Labels have IDs starting at 1. Mandatory.
• val:
  • The numeric label option to find. Use 0 for the first value option, 1 for the second, etc.
  • Use null to find segments where the label is not set. With labels configured to be always visible, a null-query is equivalent to finding the default value of the label.

Example:

"lbls": [ { "id": 1, "val": 0 }, { "id": 23, "val": 3 }, { "id": 10, "val": null } ]

When specifying multiple items, all of them must match.

Optional filter on term-level TBX fields. An array of TBX field and value pairs. Each array element has these properties:

• id: TheTBX field ID. Mandatory.
• val: The value to find.
• mode: Optional search mode. Any of "Plain" (default, prefix search), "Wildcards", "Regex" or "Empty"
• phrase: Optional phrase match flag. Default is false.

Example:

"tbx": [ { "id": "context", "val": "Mechanical" }, { "id": "example", "val": "stru*e", "mode": "Wildcards" } ]

Example to find segments with a comment containing a text:

"comments": {
	"locs": [ "fr" ],
	"txt": "grammar"
}

Filter segments that have one or more comments in either English or French or both:

"comments": {
	"locs": [ "fr", "en-US" ]
}

Optional comments category. When adding a comment to a text, the user can choose a category.

Category IDs are numbers 0, 1, 2 in the order they are shown online. The administrator can customize the categories.

The skip parameter supplied to the method.