Update

Description

Updates a single record.

Request

HTTP Method: PUT

Parameter Description
add_child_records Optional An array of record IDs to be added to the record as child records. If a record already belongs to another parent, it will be moved to the new parent (the previous parent-child relationship is removed). Adding a child record that would create a circular dependency (e.g. A is a child of B which is a child of A) will fail with a validation error.
remove_child_records Optional An array of record IDs to remove from the record as child records
add_team_case_ids Optional An array of case IDs to be linked to the record
remove_team_case_ids Optional An array of case IDs to be unlinked from the record
field_values Optional An array of objects. Each object should contain a field_id of the field you wish to update and a value for the updated value.
resolve_artifacts Optional Boolean true or false value. When true, Artifacts (large text) fields return the full contents in the response instead of just the artifact ID. Defaults to false.
include_children Optional Boolean true or false value. When true, child records are returned with their full field data. When false, child records are omitted from the response. By default, child records are returned with full field data. A maximum of 50 child records are returned.
Field values Description
field_id The ID of the field you wish to update.
value The value to update the field with.
Path Parameter Description
record_id The ID of the record to update.

Sample request

curl -X PUT \
  https://<<META.tenant.domain>>/api/v1/records/<<record_id>> \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
    "add_child_records": ["1"],
    "field_values": [{"field_id":"285","value":"true"}],
    "add_team_case_ids": ["14","19"]
  }'

Example request with resolve_artifacts

To return full artifact contents in the response instead of artifact IDs:

curl -X PUT \
  "https://<<META.tenant.domain>>/api/v1/records/<<record_id>>?resolve_artifacts=true" \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
    "field_values": [{"field_id":"285","value":"true"}]
  }'

Response

A successful request will return a JSON object representing the specified record.

Artifacts (large text)

By default, Artifacts (large text) field types return a reference object containing the artifact ID and an is_artifact flag, rather than the data itself:

{ "id": 674623, "is_artifact": true }

This id is the artifact_id you need to pass to the GET Artifacts (large text) API endpoint to retrieve the actual contents.

Alternatively, set resolve_artifacts=true in the request to include full artifact contents directly in the response.

Field description

Parameter Description
id The record ID.
created_at ISO 8601 Timestamp representing the creation date and time of the record.
updated_at ISO 8601 Timestamp representing the last update date and time of the record.
story The story the record was created from.
story_run_guid The story run guid the record was created from.
record_type The type of record the record was created for.
records The captured data for the given instance of the record type.
child_records An array of objects containing child record data. Includes full field data by default, or can be omitted with include_children=false.
child_records_truncated Boolean indicating whether the child records list was truncated. Only present when child records are included in the response.
case_ids The case IDs linked to this record.
result The captured data in key-value format.

A successful request will return a JSON object describing the updated record.

Sample response

{
  "id": 59,
  "created_at": "2023-06-14T15:09:02Z",
  "updated_at": "2023-06-14T15:10:32Z",
  "story": {
    "id": 8,
    "name": "Create new IOC"
  },
  "story_run_guid": "82c8e2c8-ab56-49c9-bdb9-1ea5b7fd5b2e",
  "record_type": {
    "id": 1,
    "name": "Alert"
  },
  "records": [
    {
      "field_id": "36",
      "name": "Story name",
      "value": "Create new IOC"
    },
    {
      "field_id": "37",
      "name": "Timestamp",
      "value": "2023-06-14 16:09:02"
    },
    {
      "field_id": "38",
      "name": "Name",
      "value": "Example"
    }
  ],
  "child_records": [
    {
      "id": 9,
      "records": [
        {
          "field_id": "39",
          "name": "Story name",
          "value": "Create new IOC"
        },
        {
          "field_id": "40",
          "name": "Timestamp",
          "value": "2023-06-14 16:09:02"
        },
        {
          "field_id": "41",
          "name": "Name",
          "value": "Example"
        }
      ]
    }
  ],
  "case_ids": [14, 19],
  "result": {
    "id": 59,
    "updated_at": "2023-06-14T15:10:32Z",
    "case_ids": [14, 19],
    "Story name": "Create new IOC",
    "Timestamp": "2023-06-14 16:09:02",
    "Name": "Example"
  }
}
Was this helpful?