HTTP API

Content requests

Requesting localization or the creation of new content is accomplished by sending a content request. Content requests can be associated with various items, but are typically linked to a webpage or a product.

A minimal request, which serves as a fundamental building block for more complex requests, might look like this:

{
  "type": "standard",
  "language": {
    "source": "en-GB",
    "target": "sv-SE"
  },
  "fields": [
    {
      "id": "title",
      "type": "localizable",
      "data": "string",
      "value": "Products"
    },
    {
      "id": "body",
      "type": "localizable",
      "data": "html",
      "value": "<p>This text could contain various <strong>HTML tags</strong></p>"
    }
  ]
}

The immediate response to a content request may resemble the following example. In the provided code snippet, the response object is enriched with several additional properties, each of which is explained in detail within the subsequent table. Note that depending of the type of the content request the values of the response differs.

{
    "type": "standard",
    "source": "api",
    "id": "8dR9QCF8oRs",
    "batchId": "HMYwpdcFCSq",
    "language": {
        "source": "en-GB",
        "target": "sv-SE"
    },
    "previous": null,
    "state": "pending",
    "fields": [
      {
        "id": "title",
        "type": "localizable",
        "data": "string",
        "originalValue": "Products"
      },
      {
        "id": "body",
        "type": "localizable",
        "data": "html",
        "originalValue": "<p>This text could contain various <strong>HTML tags</strong></p>"
      }
    ],
    "hints": [],
    "import_response": null,
    "created": "2023-10-20T07:43:14.000Z",
    "lastStateChange": "2023-10-20T07:43:14.000Z",
}

A content request can contain the following information. Note that all properties that isn't marked as Only readable can also be specified for the content requests that are sent to the API.

Name	Type	Description
`type`	type (string)	The type of request, will be `standard` if not specified, see types.
`source`	string	Indicates that the request was handled by the API Only readable
`id`	string	Unique identifier generated when a content request is received by the API. Only readable
`batchId`	string	Unique grouping identifier generated for multiple requests
`language.source`	Locale	Language that the source text, field names and hints is in. Required
`language.target`	Locale	Language that the content should be written in. Required
`previous`	id (string)	Only used for `update` requests. Unique identifier of the last version of the content sent.
`state`	state (string)	State of the request. See section below for details. Only readable
`fields`	Array [Field]	One or more fields containing either information or something that should be localized or written. Required
`hints`	Array [Hints]	A list of hints for the request (applies to machine translation requests)
`import_response`	string	An indicator that may be set to mark a successful import, see content
`created`	Timestamp	When the request was received by the API. Only readable
`lastStateChange`	Timestamp	When the state of the request was last updated. Only readable
`completed`	Timestamp	When the request was marked as completed. Only readable

Warning

Unknown JSON properties on a content request should be ignored. This is important for future compatibility as the HTTP API may introduce new properties at times. Existing fields will never be deleted.

Types

The API supports different types of content requests, the standard type represents a simple request for some content to be translated or created.

Type	Description
`localize`	Standard request for localization.
`standard`	Standard request for translation or content creation.
`import`	Import some already existing content for use with versioning.
`update`	Update a previous content request with some altered content.

Localize requests

Localize requests are those that have type set to localize. These requests will be localized with a higher quality than the standard translation.

Standard requests

Standard requests are those that have no type set or those that have type set to standard.

Import requests

To support versioning of already localized content it's possible to import content. A content request that is to be imported is similar to a standard request, but is marked with the type import. In addition to this every field in the request requires both originalValue and value. When an import request is sent it is automatically marked as completed as no work will be done with it, you can then reference the id returned when sending update requests.

Example:

{
  "type": "import",
  "language": {
    "source": "en-GB",
    "target": "sv-SE"
  },
  "fields": [
    {
      "id": "body",
      "type": "localizable",
      "data": "html",
      "originalValue": "<p>This text could contain various <strong>HTML tags</strong></p>",
      "value": "<p>Denna text kan innehålla <strong>HTML taggar</strong></p>"
    }
  ]
}

Update requests

When you need to send an update to a content request that you've sent before (including imported requests), you can specify the request type as update, supplying the id of the previous request within the request body.

In an update request, you must include all the fields that would typically be part of a standard request. To identify what has changed, we compare the old field values with the new ones using their unique identifiers.

If the update-request does not contain all the fields that were included in the original (previous) request (matching the field id) a validation error will occur and be sent back to the client.

Adding entirely new fields is currently not possible in an update request. The update should only include existing fields that need modifications.

{
  "type": "update",
  "previous": "idOfPreviousVersion",
  "language": {
    "source": "en-GB",
    "target": "sv-SE"
  },
  "fields": [
    {
      "id": "body",
      "type": "localizable",
      "data": "html",
      "value": "<p>This text could contain updated content</p>"
    }
  ]
}

States

Every content request has a state and will pass through certain states before it is completed.

State	Description
`pending`	The request has been received by the API.
`confirmed`	Request has been processed by Contentor and will be fulfilled soon.
`completed`	The request has been completed and the content is ready for use.
`canceled`	The request has been canceled and will not be worked on.
`failed`	The content request has failed at some part of the process, no work worked on it and it will need to be resent. The is most likely due to faulty html content.

States can change backwards, such as from completed to confirmed such as in the case where a request is reopened for updates.

Fields

Content request are built up of one or more fields. Fields are used both to request a localization of a text, the creation of a text and to deliver contextual information needed to work with a content request.

See format of fields for details about the format used for fields.

Related pages

Fields

Content API