ByteArk Documentation

# Working with custom fields

# Concept

We provide 3 styles of custom field requests/response formats to made it easy to develop with your programming language

  • simpleCustomFields: For reading/writing custom fields with key-value style, with very simple usage
  • customFields: For reading/writing custom fields with key-value style, with more relation information
  • customFieldEntries: For reading/writing custom fields with array of fields style, good for type-safe manner

All 3 formats will represent the same content. Feel free to use the one you would like.

# Getting custom fields from a video

When getting a video, the response will include all 3 formats of custom fields.

# Endpoint

GET https://stream.byteark.com/api/v1/videos/<videoKey>
1

# Example Response

TIP

The detail of the custom fields are redacted. We'll learn about each format after this.

{
  "videoKey": "<videoKey>",
  "simpleCustomFields": {
  },
  "customFields": {
  },
  "customFieldEntries": [
    {
      "fieldId": "621dd854475a694976c36037",
      "type": "text",
      "numberValue": "This should be popular",
      "field": {
        "fieldName": "note",
        "displayName": "Note",
        "type": "text",
        "id": "621dd854475a694976c36037"
      }
    },
    {
      "fieldId": "621dd854475a694976c36038",
      "type": "number",
      "numberValue": 1,
      "field": {
        "fieldName": "episode_no",
        "displayName": "Episode Number",
        "type": "number",
        "id": "621dd854475a694976c36038"
      }
    },
    {
      "fieldId": "621dd854475a694976c36039",
      "type": "switch",
      "numberValue": true,
      "field": {
        "fieldName": "recommended",
        "displayName": "Recommended",
        "type": "switch",
        "id": "621dd854475a694976c36039"
      }
    },
    {
      "fieldId": "621dd83c7909e74c2ba6584e",
      "type": "labels",
      "labelsValue": {
        "type": "labels",
        "labelIds": [
          "6320b0b1dc6da9ae81c5fa71"
        ],
        "labels": [
          {
            "teamNamespace": "inox-dev",
            "fieldId": "621dd83c7909e74c2ba6584e",
            "name": "test",
            "globalUniqueName": "field-621dd83c7909e74c2ba6584e/test",
            "deleted": false,
            "createdAt": "2022-09-13T16:32:49.684Z",
            "updatedAt": "2022-09-13T16:32:49.684Z",
            "id": "6320b0b1dc6da9ae81c5fa71"
          }
        ],
        "labelNames": [
          "test"
        ]
      },
      "field": {
        "fieldName": "content_type",
        "displayName": "Content Type",
        "type": "labels",
        "id": "621dd83c7909e74c2ba6584e"
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

# Custom fields in simpleCustomFields format

In simpleCustomFields format, the custom fields will be formatted in key-value style, with simple data type.

For complex data, such as labels, it will represented as an array of string.

{
  "simpleCustomFields": {
    "note": "This should be popular",
    "episode_no": 1,
    "recommended": true,
    "content_type": ["test"]
  }
}
1
2
3
4
5
6
7
8

# Custom fields in customFields format

In customFields format, the custom fields will be formatted in key-value style, but for complext data, it will represent detailed information.

This format is useful when you need to access the ID of labels.

{
"customFields": {
    "note": "This should be popular",
    "episode_no": 1,
    "recommended": true,
    "content_type": {
      "type": "labels",
      "labelIds": [
        "6320b0b1dc6da9ae81c5fa71"
      ],
      "labels": [
        {
          "name": "test",
          "id": "6320b0b1dc6da9ae81c5fa71"
        }
      ],
      "labelNames": [
        "test"
      ]
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Custom fields in customFieldEntries format

In customFieldEntries format, the custom fields will be response with the format that can be described as an array of fields.

This format is useful for the developer that prefers type-safe, or want to use the value with the related field information.

"customFieldEntries": [
    {
      "fieldId": "621dd854475a694976c36037",
      "type": "text",
      "numberValue": "This should be popular",
      "field": {
        "fieldName": "note",
        "displayName": "Note",
        "type": "text",
        "id": "621dd854475a694976c36037"
      }
    },
    {
      "fieldId": "621dd854475a694976c36038",
      "type": "number",
      "numberValue": 1,
      "field": {
        "fieldName": "episode_no",
        "displayName": "Episode Number",
        "type": "number",
        "id": "621dd854475a694976c36038"
      }
    },
    {
      "fieldId": "621dd854475a694976c36039",
      "type": "switch",
      "numberValue": true,
      "field": {
        "fieldName": "recommended",
        "displayName": "Recommended",
        "type": "switch",
        "id": "621dd854475a694976c36039"
      }
    },
    {
      "fieldId": "621dd83c7909e74c2ba6584e",
      "type": "labels",
      "labelsValue": {
        "type": "labels",
        "labelIds": [
          "6320b0b1dc6da9ae81c5fa71"
        ],
        "labels": [
          {
            "name": "test",
            "globalUniqueName": "field-621dd83c7909e74c2ba6584e/test",
            "id": "6320b0b1dc6da9ae81c5fa71"
          }
        ],
        "labelNames": [
          "test"
        ]
      },
      "field": {
        "fieldName": "content_type",
        "displayName": "Content Type",
        "type": "labels",
        "id": "621dd83c7909e74c2ba6584e"
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

# Updating custom fields to a video, with simpleCustomFields

For now, we only allow updating custom fields with simpleCustomFields.

# Endpoint

PUT https://stream.byteark.com/api/v1/videos/<videoKey>/custom-fields
1

# Example Request Body

{
  "simpleCustomFields": {
    "note": "Sample video",
    "content_type": ["test"],
    "episode_no": 1
  }
}
1
2
3
4
5
6
7

# Example Response

The response will include the custom fields in all 3 formats:

TIP

The detail of the custom fields are redacted.

{
  "videoKey": "<videoKey>",
  "simpleCustomFields": {
  },
  "customFields": {
  },
  "customFieldEntries": [
  ]
}
1
2
3
4
5
6
7
8
9

# Getting available options for labels

For labels type, we can get available labels via API.

# Endpoint

TIP

Please noted that we'll need customFieldId, by getting customFieldEntries in this case.

GET https://stream.byteark.com/api/v1/custom-field-labels?customFieldId={customFieldId}
1

You may also search for labels by keyword:

GET https://stream.byteark.com/api/v1/custom-field-labels?customFieldId={customFieldId}&q={searchKeyword}
1

# Example Response

[
  {
    "fieldId": "621dd83c7909e74c2ba6584e",
    "name": "Sample Label 1",
    "globalUniqueName": "field-621dd83c7909e74c2ba6584e/sample-label-1",
    "deleted": false,
    "createdAt": "2022-09-13T16:32:49.684Z",
    "updatedAt": "2022-09-13T16:32:49.684Z",
    "id": "6320b0b1dc6da9ae81c5fa71"
  },
  {
    "fieldId": "621dd83c7909e74c2ba6584e",
    "name": "Sample Label 2",
    "globalUniqueName": "field-621dd83c7909e74c2ba6584e/sample-label-2",
    "deleted": false,
    "createdAt": "2022-09-13T16:32:49.684Z",
    "updatedAt": "2022-09-13T16:32:49.684Z",
    "id": "6320b0b1dc6da9ae81c5fa72"
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Pricing Contact Terms of Service