Skip to main content
Kinetic Community

Facts/Unknowns

Facts and Unknowns are objects that can be added to an Issue to help facilitate discussion / problem solving. This document describes how to Add, Edit, Delete and Fetch Facts and Unknowns.

Creating a Fact or Unknown

HTTP Request

Method: POST

URL: /api/v1/issues/<issue_guid>/facts

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

Body Content for a fact (note that confirmed = true)

{
  "body": "This is a fact ",
  "confirmed": true
}

Body Content for an unknown:

{
  "body": "This is an unknown ",
  "confirmed": false
}

 

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body corresponding to the newly created fact or unknown.

 

Example Response:

{
    "id": 490,
    "body": "POSTMAN fact ",
    "issue_id": 387,
    "user_id": 71,
    "confirmed": true,
    "created_at": "2015-04-01T14:24:54.522-05:00",
    "updated_at": "2015-04-01T14:24:54.522-05:00",
    "deleted_at": null,
    "status": "Active",
    "guid": "bd8eb89e-f5c0-46c0-8962-30cef5833600"
}

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Example of a failed request:

Response Code: 422 

Response Body:

{
"message": "Unprocessable attributes",
"reasons": 
    [
        "Body Fact & Unknown text cannot be blank."
    ]
}

 

Response Codes

Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
422 A required field was left out.
500 If there was an unexpected server error.

 


Editing a Fact or Unknown

HTTP Request

Method: PUT

URL: /api/v1/issues/<issue_guid>/facts/<fact_unknown_guid>

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

 

Body Content:

Both "body" and "confirmed" can be modified.

{
  "body": "This is a fact ",
  "confirmed": true
}

 

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body corresponding to a single Fact or Unknown.

 

Example Response:

{
    "id": 497,
    "body": "Hello.",
    "issue_id": 376,
    "user_id": 71,
    "confirmed": false,
    "created_at": "2015-04-01T14:49:31.610-05:00",
    "updated_at": "2015-04-01T14:51:24.453-05:00",
    "deleted_at": null,
    "status": "Active",
    "guid": "06f99ce9-edd4-4373-9ccd-6cdbdb42c53a"
}

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Response Codes

Response Code Reason
200 Successful request.
400 Bad Request. Json might have a field named incorrectly.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.

 

Deleting a Fact or Unknown

Edit section

HTTP Request

Edit section

Method: DELETE

URL: /api/v1/issues/<issue_guid>/facts/<fact_unknown_guid>

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

 

HTTP Response

Edit section

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code.

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Response Codes

Edit section
Response Code Reason
200 Successful request.
400 Bad Request. Json might have a field named incorrectly.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.
 

Fetching Facts and Unknowns

A list of Facts and Unknowns can be fetched for a particular issue.

HTTP Request

Method: GET

URL: /api/v1/issues/<issue_guid>/facts

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

 

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body corresponding to an array of Facts or Unknowns.

 

Example Response:

[
    {
        "id": 497,
        "body": "Hello.",
        "issue_id": 376,
        "user_id": 71,
        "confirmed": false,
        "created_at": "2015-04-01T14:49:31.610-05:00",
        "updated_at": "2015-04-01T14:51:24.453-05:00",
        "deleted_at": "2015-04-01T15:01:16.335-05:00",
        "status": "Deleted",
        "guid": "06f99ce9-edd4-4373-9ccd-6cdbdb42c53a"
    }
]

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Example of a failed request:

Response Code: 401 

Response Body:

{
    "success": false,
    "message": "Error with your login or password"
}

 

Response Codes

Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.

Fetching Single Fact or Unknown

Edit section

A single Fact or Unknown can be fetched for a particular issue.

HTTP Request

Edit section

Method: GET

URL: /api/v1/issues/<issue_guid>/facts/<fact_guid>

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

 

HTTP Response

Edit section

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body corresponding to a single Fact or Unknown.

Example Response:

[
    {
        "id": 497,
        "body": "Hello.",
        "issue_id": 376,
        "user_id": 71,
        "confirmed": false,
        "created_at": "2015-04-01T14:49:31.610-05:00",
        "updated_at": "2015-04-01T14:51:24.453-05:00",
        "deleted_at": "2015-04-01T15:01:16.335-05:00",
        "status": "Deleted",
        "guid": "06f99ce9-edd4-4373-9ccd-6cdbdb42c53a"
    }
]

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Example of a failed request:

Response Code: 401 

Response Body:

{
    "success": false,
    "message": "Error with your login or password"
}

 

Response Codes

Edit section
Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.