GET /api/v2/annotations/:id
Show an annotation

Examples

GET /api/v2/annotations/16
200
{
  "data": {
    "id": "16",
    "type": "annotations",
    "links": {
      "self": "http://test.host/api/v2/annotations/16"
    },
    "attributes": {
      "message": "MyString",
      "annotable-attribute": "executive_summary",
      "section-id": 11,
      "is-starred": false,
      "is-secret": false,
      "created-at": "2017-08-29T10:49:29.421+08:00"
    },
    "relationships": {
      "annotator": {
        "links": {
          "self": "http://test.host/api/v2/annotations/16/relationships/annotator",
          "related": "http://test.host/api/v2/annotations/16/annotator"
        }
      },
      "annotable": {
        "links": {
          "self": "http://test.host/api/v2/annotations/16/relationships/annotable",
          "related": "http://test.host/api/v2/annotations/16/annotable"
        }
      }
    }
  }
}

Params

Param name Description
id
required

Annotation ID

Validations:

  • Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hyphen(-) with no leading or trailing space.


POST /api/v2/annotations
Post an annotation on an insight

Examples

POST /api/v2/annotations
{
  "data": {
    "type": "annotations",
    "attributes": {
      "message": "MyString",
      "annotable-attribute": "executive_summary",
      "section-id": "71",
      "is-starred": false,
      "is-secret": false,
      "created-at": null
    },
    "relationships": {
      "annotable": {
        "data": {
          "type": "insights",
          "id": "151"
        }
      }
    }
  }
}
201
{
  "data": {
    "id": "2",
    "type": "annotations",
    "links": {
      "self": "http://test.host/api/v2/annotations/2"
    },
    "attributes": {
      "message": "MyString",
      "annotable-attribute": "executive_summary",
      "section-id": 71,
      "is-starred": false,
      "is-secret": true,
      "created-at": "2017-08-29T10:49:05.442+08:00"
    },
    "relationships": {
      "annotator": {
        "links": {
          "self": "http://test.host/api/v2/annotations/2/relationships/annotator",
          "related": "http://test.host/api/v2/annotations/2/annotator"
        }
      },
      "annotable": {
        "links": {
          "self": "http://test.host/api/v2/annotations/2/relationships/annotable",
          "related": "http://test.host/api/v2/annotations/2/annotable"
        }
      }
    }
  }
}

Params

Param name Description
data
required

Annotation information

Validations:

  • Must be a Hash

data[type]
required

Validations:

data[attributes]
required

Validations:

  • Must be a Hash

data[attributes][message]
required

Annotation message

Validations:

  • Must be a String

data[attributes][annotable-attribute]
required

Validations:

  • Must be one of: executive_summary, detail.

data[attributes][section-id]
required

Section id of the content being annotated

Validations:

  • Must be a Integer

data[attributes][starred]
required

Annotation message is starred

Validations:

  • Must be one of: true, false.

data[attributes][secret]
required

Annotation is secret

Validations:

  • Must be one of: true, false.

data[relationships]
required

Validations:

  • Must be a Hash

data[relationships][annotator]
required

Validations:

  • Must be a Hash

data[relationships][annotator][data]
required

Validations:

  • Must be a Hash

data[relationships][annotator][data][type]
required

Account type, which is `accounts`

Validations:

  • Must be a String

data[relationships][annotator][data][id]
required

Account ID who is commenting

Validations:

  • Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hyphen(-) with no leading or trailing space.

data[relationships][annotable]
required

Validations:

  • Must be a Hash

data[relationships][annotable][data]
required

Validations:

  • Must be an Array of nested elements

data[relationships][annotable][data][type]
required

Content being annotated on, which is `insights`

Validations:

  • Must be a String

data[relationships][annotable][data][id]
required

Insight ID

Validations:

  • Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hyphen(-) with no leading or trailing space.


PATCH /api/v2/annotations/:id
Post an annotation on an insight

Examples

PATCH /api/v2/annotations/1
{
  "data": {
    "id": "1",
    "type": "annotations",
    "attributes": {
      "message": "MyString",
      "annotable-attribute": "executive_summary",
      "section-id": "30",
      "is-starred": true,
      "is-secret": false,
      "created-at": "2017-08-29 10:49:03 +0800"
    },
    "relationships": {
      "annotator": {
        "data": {
          "type": "annotators",
          "id": "888"
        }
      },
      "annotable": {
        "data": {
          "type": "annotables",
          "id": "150"
        }
      }
    }
  }
}
401
{
  "errors": [
    {
      "title": "You are not authorized to access this request"
    }
  ]
}

Params

Param name Description
id
required

Annotation ID

Validations:

  • Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hyphen(-) with no leading or trailing space.

data
required

Annotation information

Validations:

  • Must be a Hash

data[type]
optional

Validations:

data[attributes]
optional

Validations:

  • Must be a Hash

data[attributes][starred]
optional

Annotation is starred

Validations:

  • Must be one of: true, false.


DELETE /api/v2/annotations/:id
Delete own annotation on an insight

Examples

DELETE /api/v2/annotations/17
204
{}

Params

Param name Description
id
required

Comment ID

Validations:

  • Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hyphen(-) with no leading or trailing space.