Related pages

HTTP API

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.

A field object contains the following values:

Name Type Description
id string Identifier of the field, use this for retrieval of field data and querying of requests.
name string Human readable name of the field. Optional, id is used if this value is not provided.
type type How this field should be treated, either internal, context or localizable. Required
data data type The type of data this field contains, two types are currently supported: string and html. Required
value dynamic Value of this field. Required for internal, context and localizable, has to be nullfor creatable fields.
originalValue dynamic Original value of this field. Only readable
intermediateValue dynamic Intermediate value of this field. Used for things such as machine translation that can deliver unfinished values for early use. Only readable

Field types

Name Description
internal Used for storing data relevant to the submitter but that does not affect the localization and creation of content.
context Contextual information to help writers with localization and content creation.
localizable Used for fields where the value should be localized into another language.
creatable Used for fields where content should be created based on context and hints.

Data types

Name Description
string String of text - no formatting and will not be encoded. JSON data is expected to be a string.
html HTML formatted text, needs to be a valid HTML fragment and will be returned HTML encoded. JSON data is expected to be a string.
html:relaxed Like html but will not use strong validation.
Warning

HTML can be messy and our html type uses strong validation to help us write correct HTML. This means that we will validate against the same rules that the W3C Markup Validation Service uses. In certain cases the markup you want to send us might not validate, in which case you can switch to html:relaxed to avoid the use of strong validation.

Hints

Hints can be placed on fields to help with creating better content for you. There are both soft hints, such as target word count and harder ones such as a maximum length to enforce at datababse limit. Different types of fields can support different types of hints. Hints are specified via an array on the field named hints. Example:

{
  "id": "title",
  "type": "localizable",
  "data": "string",
  "value": "Produkter",
  "hints": [
    {
      "type": "length",
      "max": 400
    }
  ]
}

Length limit

Limit the length of the text in a field.

Type: length Use: Works for localizable and creatable fields.

Argument Description
around Optional length of the text, used as an indicator of a desired length, but the finished text can be shorter than this text.
max Optional maximum length of the returned text. The finished text will never be longer than this.

Word count

Set a target on the number of words a text should have.

Type: word-count Use: Only with field type creatable.

Argument Description
around Number of words that the created text should aim for. Used as an indicator on how many words the text should have, but a returned text is allowed to have less words.

Free text

Ties some free text information to a field, similar to context but scoped to a single field.

Type: free-text Use: Works for localizable and creatable fields.

Argument Description
text The text that should be associated with this field.

Examples of fields

Internal field, that can be queried but is not visible during localization and content creation:

{
  "id": "database-id",
  "type": "internal",
  "data": "string",
  "value": "1457355474317"
}

Context field, can be queried and is shown during localization and content creation:

{
  "id": "product-type",
  "type": "context",
  "data": "string",
  "value": "Coffee Brewer"
}

Localizable field, can be queried and should be localized:

{
  "id": "product-listing-text",
  "type": "localizable",
  "data": "html",
  "value": "Coffee Brewer with integrated timer & automatic shut down."
}

Retrieve a localized field:

{
  "id": "product-listing-text",
  "type": "localizable",
  "data": "html",
  "value": "Kaffebryggare med integrerad timer & automatisk avstängning.",
  "originalValue": "Coffee Brewer with integrated timer & automatic shut down."
}

Creatable field with a few hints:

{
  "id": "short description",
  "type": "creatable",
  "data": "html",
  "hints": [
    {
      "type": "free-text",
      "text": "Summarize product description"
    },
    {
      "type": "word-count",
      "around": 100
    }
  ]
}

Retrieve a creatable field:

{
  "id": "short description",
  "type": "creatable",
  "data": "html",
  "value": "Coffee Brewer with integrated timer & automatic shut down.",
  "hints": [
    {
      "type": "free-text",
      "text": "Summarize product description"
    },
    {
      "type": "word-count",
      "around": 100
    }
  ]
}