Jobs API (v2.0)

Use the Jobs API to retrieve, create, update, and delete job targets or the description. This REST API lets you interact with:

  • M.Target entities, which are targets of a job.
  • The M.JobDescription entity, which contains information about what to do and what is in progress.

Note
To help you switch to the Jobs API, we provide guidance on how to update calls in your code.

Authentication

To use the Try it feature of the Jobs API, you need:

Download OpenAPI description
Overview
Languages
Servers
https://{server}/

Jobs

The Jobs endpoint is used to retrieve a specific job.

Operations

Job description

The Job description entity contains information for the worker about what needs to be done and what is in progress.

Operations

Retrieve the job description

Request

Retrieves the description for a specific job using its ID, for example 39595.

Path
idinteger(int64)required

The ID for the job, for example 39596.

Query
culturesArray of strings

List of cultures in which to load the entity. If no cultures are provided, multi-language properties are not included.

curl -i -X GET \
  'https://your-server/api/jobs/{id}/description?cultures=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation.

Bodyapplication/json
idinteger(int64)

The ID for the entity, for example 39752.

identifierstring or null

The identifier for the entity.

culturesArray of strings or null

The cultures associated with the entity, for example en-US.

propertiesobject or null

The properties of the entity.

relationsobject or null

The relations of the entity.

created_byobject(Link)

Represents a link to a resource.

created_onstring(date-time)

The date and time when the entity was created.

modified_byobject(Link)

Represents a link to a resource.

modified_onstring(date-time)

The date and time when the entity was last modified.

locked_byobject(Link)

Represents a link to a resource.

locked_onstring or null(date-time)

The date and time when the entity was locked.

entitydefinitionobject(Link)

Represents a link to a resource.

copyobject(Link)

Represents a link to a resource.

copyasyncobject(Link)

Represents a link to a resource.

permissionsobject(Link)

Represents a link to a resource.

requested_permissionsobject or null

The requested permissions with identification if a certain user has permission.

lifecycleobject(Link)

Represents a link to a resource.

saved_selectionsobject(Link)

Represents a link to a resource.

rolesobject(Link)

Represents a link to a resource.

annotationsobject(Link)

Represents a link to a resource.

is_root_taxonomy_itemboolean or null

Gets or sets a value indicating whether the entity is a root taxonomy item.

is_path_rootboolean or null

Gets or sets a value indicating whether the entity is a path root.

inherits_securityboolean

Gets or sets a value indicating whether the entity inherits security.

is_system_ownedboolean

Gets or sets a value indicating whether the entity is system owned.

versioninteger(int64)

The version of the entity.

fullobject(Link)

Represents a link to a resource.

modulesArray of strings or null

The modules associated with the entity.

selfobject(Link)

Represents a link to a resource.

property name*anyadditional property
Response
application/json
{ "id": 0, "identifier": "string", "cultures": [ "string" ], "properties": { "property1": {}, "property2": {} }, "relations": { "property1": {}, "property2": {} }, "created_by": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "created_on": "2019-08-24T14:15:22Z", "modified_by": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "modified_on": "2019-08-24T14:15:22Z", "locked_by": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "locked_on": "2019-08-24T14:15:22Z", "entitydefinition": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "copy": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "copyasync": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "permissions": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "requested_permissions": { "property1": true, "property2": true }, "lifecycle": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "saved_selections": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "roles": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "annotations": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "is_root_taxonomy_item": true, "is_path_root": true, "inherits_security": true, "is_system_owned": true, "version": 0, "full": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "modules": [ "string" ], "self": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "property1": null, "property2": null }

Create or update the job description

Request

Creates a job description entity if it does not exist or updates the job description entity. It confirms that the job exists and that the user has permission to access it. Properties or relations not included in the request will be set to null.

Path
idinteger(int64)required

The ID for the job, for example 39596.

Bodyapplication/jsonrequired

The request containing the job description information.

idinteger or null(int64)

The unique job description ID.

identifierstring or null

The unique job description identifier.

propertiesobject or null

The job description properties.

relationsobject or null

The job description relations.

is_root_taxonomy_itemboolean or null

A value indicating whether the job description is a root taxonomy item.

is_path_rootboolean or null

A value indicating whether the job description is a path root.

entity_definitionobject(Link)

Represents a link to a resource.

is_system_ownedboolean

A value indicating whether the job description is system owned.

inherits_securityboolean

A value indicating whether the job description inherits security.

selfobject(Link)

Represents a link to a resource.

curl -i -X PUT \
  'https://your-server/api/jobs/{id}/description' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 0,
    "identifier": "string",
    "properties": {
      "property1": {},
      "property2": {}
    },
    "relations": {
      "property1": {
        "parents": [
          {
            "properties": {
              "property1": {},
              "property2": {}
            },
            "renditions": {
              "property1": {},
              "property2": {}
            },
            "permissions": [
              "string"
            ],
            "identifier": "string",
            "href": "string",
            "filename_properties": [
              "string"
            ],
            "title": "string",
            "templated": false
          }
        ],
        "parent": {
          "properties": {
            "property1": {},
            "property2": {}
          },
          "renditions": {
            "property1": {},
            "property2": {}
          },
          "permissions": [
            "string"
          ],
          "identifier": "string",
          "href": "string",
          "filename_properties": [
            "string"
          ],
          "title": "string",
          "templated": false
        },
        "children": [
          {
            "properties": {
              "property1": {},
              "property2": {}
            },
            "renditions": {
              "property1": {},
              "property2": {}
            },
            "permissions": [
              "string"
            ],
            "identifier": "string",
            "href": "string",
            "filename_properties": [
              "string"
            ],
            "title": "string",
            "templated": false
          }
        ],
        "child": {
          "properties": {
            "property1": {},
            "property2": {}
          },
          "renditions": {
            "property1": {},
            "property2": {}
          },
          "permissions": [
            "string"
          ],
          "identifier": "string",
          "href": "string",
          "filename_properties": [
            "string"
          ],
          "title": "string",
          "templated": false
        },
        "inherits_security": true,
        "parent_total": 0,
        "child_total": 0,
        "self": {
          "href": "string",
          "filename_properties": [
            "string"
          ],
          "title": "string",
          "templated": false
        }
      },
      "property2": {
        "parents": [
          {
            "properties": {
              "property1": {},
              "property2": {}
            },
            "renditions": {
              "property1": {},
              "property2": {}
            },
            "permissions": [
              "string"
            ],
            "identifier": "string",
            "href": "string",
            "filename_properties": [
              "string"
            ],
            "title": "string",
            "templated": false
          }
        ],
        "parent": {
          "properties": {
            "property1": {},
            "property2": {}
          },
          "renditions": {
            "property1": {},
            "property2": {}
          },
          "permissions": [
            "string"
          ],
          "identifier": "string",
          "href": "string",
          "filename_properties": [
            "string"
          ],
          "title": "string",
          "templated": false
        },
        "children": [
          {
            "properties": {
              "property1": {},
              "property2": {}
            },
            "renditions": {
              "property1": {},
              "property2": {}
            },
            "permissions": [
              "string"
            ],
            "identifier": "string",
            "href": "string",
            "filename_properties": [
              "string"
            ],
            "title": "string",
            "templated": false
          }
        ],
        "child": {
          "properties": {
            "property1": {},
            "property2": {}
          },
          "renditions": {
            "property1": {},
            "property2": {}
          },
          "permissions": [
            "string"
          ],
          "identifier": "string",
          "href": "string",
          "filename_properties": [
            "string"
          ],
          "title": "string",
          "templated": false
        },
        "inherits_security": true,
        "parent_total": 0,
        "child_total": 0,
        "self": {
          "href": "string",
          "filename_properties": [
            "string"
          ],
          "title": "string",
          "templated": false
        }
      }
    },
    "is_root_taxonomy_item": true,
    "is_path_root": true,
    "entity_definition": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "is_system_owned": true,
    "inherits_security": true,
    "self": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    }
  }'

Responses

Job description successfully created.

Partially update the job description

Request

Updates part of the job description entity. It confirms that both the job and description exist and that the user has permission to modify them. Properties or relations not included in the request will be set to null.

Path
idinteger(int64)required

The ID for the job, for example 39596.

Bodyapplication/jsonrequired

The request containing the updated job description information.

idinteger(int64)

The ID for the entity, for example 39752.

identifierstring or null

The identifier for the entity.

culturesArray of strings or null

The cultures associated with the entity, for example en-US.

propertiesobject or null

The properties of the entity.

relationsobject or null

The relations of the entity.

created_byobject(Link)

Represents a link to a resource.

created_onstring(date-time)

The date and time when the entity was created.

modified_byobject(Link)

Represents a link to a resource.

modified_onstring(date-time)

The date and time when the entity was last modified.

locked_byobject(Link)

Represents a link to a resource.

locked_onstring or null(date-time)

The date and time when the entity was locked.

entitydefinitionobject(Link)

Represents a link to a resource.

copyobject(Link)

Represents a link to a resource.

copyasyncobject(Link)

Represents a link to a resource.

permissionsobject(Link)

Represents a link to a resource.

requested_permissionsobject or null

The requested permissions with identification if a certain user has permission.

lifecycleobject(Link)

Represents a link to a resource.

saved_selectionsobject(Link)

Represents a link to a resource.

rolesobject(Link)

Represents a link to a resource.

annotationsobject(Link)

Represents a link to a resource.

is_root_taxonomy_itemboolean or null

Gets or sets a value indicating whether the entity is a root taxonomy item.

is_path_rootboolean or null

Gets or sets a value indicating whether the entity is a path root.

inherits_securityboolean

Gets or sets a value indicating whether the entity inherits security.

is_system_ownedboolean

Gets or sets a value indicating whether the entity is system owned.

versioninteger(int64)

The version of the entity.

fullobject(Link)

Represents a link to a resource.

modulesArray of strings or null

The modules associated with the entity.

selfobject(Link)

Represents a link to a resource.

property name*anyadditional property
curl -i -X PATCH \
  'https://your-server/api/jobs/{id}/description' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 0,
    "identifier": "string",
    "cultures": [
      "string"
    ],
    "properties": {
      "property1": {},
      "property2": {}
    },
    "relations": {
      "property1": {},
      "property2": {}
    },
    "created_by": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "created_on": "2019-08-24T14:15:22Z",
    "modified_by": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "modified_on": "2019-08-24T14:15:22Z",
    "locked_by": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "locked_on": "2019-08-24T14:15:22Z",
    "entitydefinition": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "copy": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "copyasync": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "permissions": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "requested_permissions": {
      "property1": true,
      "property2": true
    },
    "lifecycle": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "saved_selections": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "roles": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "annotations": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "is_root_taxonomy_item": true,
    "is_path_root": true,
    "inherits_security": true,
    "is_system_owned": true,
    "version": 0,
    "full": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "modules": [
      "string"
    ],
    "self": {
      "href": "string",
      "filename_properties": [
        "string"
      ],
      "title": "string",
      "templated": false
    },
    "property1": null,
    "property2": null
  }'

Responses

Entity successfully updated.

Delete the job description

Request

Deletes the description associated with a job. It confirms that both the job and description exist and that the user has permission to access them.

Path
idinteger(int64)required

The ID for the job, for example 39596.

curl -i -X DELETE \
  'https://your-server/api/jobs/{id}/description' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful deletion.

Retrieve the job description

Request

Retrieves the description for a specific job using its ID, for example 39595.

Path
idinteger(int64)required

The ID for the job, for example 39596.

descriptionIdinteger(int64)required

The ID for the job description, for example 98765.

Query
culturesArray of strings

List of cultures in which to load the entity. If no cultures are provided, multi-language properties are not included.

curl -i -X GET \
  'https://your-server/api/jobs/{id}/description/{descriptionId}?cultures=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful operation.

Bodyapplication/json
idinteger(int64)

The ID for the entity, for example 39752.

identifierstring or null

The identifier for the entity.

culturesArray of strings or null

The cultures associated with the entity, for example en-US.

propertiesobject or null

The properties of the entity.

relationsobject or null

The relations of the entity.

created_byobject(Link)

Represents a link to a resource.

created_onstring(date-time)

The date and time when the entity was created.

modified_byobject(Link)

Represents a link to a resource.

modified_onstring(date-time)

The date and time when the entity was last modified.

locked_byobject(Link)

Represents a link to a resource.

locked_onstring or null(date-time)

The date and time when the entity was locked.

entitydefinitionobject(Link)

Represents a link to a resource.

copyobject(Link)

Represents a link to a resource.

copyasyncobject(Link)

Represents a link to a resource.

permissionsobject(Link)

Represents a link to a resource.

requested_permissionsobject or null

The requested permissions with identification if a certain user has permission.

lifecycleobject(Link)

Represents a link to a resource.

saved_selectionsobject(Link)

Represents a link to a resource.

rolesobject(Link)

Represents a link to a resource.

annotationsobject(Link)

Represents a link to a resource.

is_root_taxonomy_itemboolean or null

Gets or sets a value indicating whether the entity is a root taxonomy item.

is_path_rootboolean or null

Gets or sets a value indicating whether the entity is a path root.

inherits_securityboolean

Gets or sets a value indicating whether the entity inherits security.

is_system_ownedboolean

Gets or sets a value indicating whether the entity is system owned.

versioninteger(int64)

The version of the entity.

fullobject(Link)

Represents a link to a resource.

modulesArray of strings or null

The modules associated with the entity.

selfobject(Link)

Represents a link to a resource.

property name*anyadditional property
Response
application/json
{ "id": 0, "identifier": "string", "cultures": [ "string" ], "properties": { "property1": {}, "property2": {} }, "relations": { "property1": {}, "property2": {} }, "created_by": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "created_on": "2019-08-24T14:15:22Z", "modified_by": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "modified_on": "2019-08-24T14:15:22Z", "locked_by": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "locked_on": "2019-08-24T14:15:22Z", "entitydefinition": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "copy": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "copyasync": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "permissions": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "requested_permissions": { "property1": true, "property2": true }, "lifecycle": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "saved_selections": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "roles": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "annotations": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "is_root_taxonomy_item": true, "is_path_root": true, "inherits_security": true, "is_system_owned": true, "version": 0, "full": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "modules": [ "string" ], "self": { "href": "string", "filename_properties": [], "title": "string", "templated": false }, "property1": null, "property2": null }

Targets

A target entity is a target of a job (meaning a background process). Each job can have one or more targets.

Operations