Skip to main content
Kinetic Community

Issues

This resource describes creating and modifying Issues using the Kinetic Response API. TODO: Tagging, Search?,

Creating an Issue

HTTP Request

Method: POST

URL: /api/v1/issues

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

Body Content:

{
  "name":"This is an issue name",
  "description": "This is a description",
  "owner_id": 71
}

 

Parameters

 

Route Parameter Name Description Required / Optional
name The Issue name Required
description A description of the Issue Optional
owner_id Specify the id of the Issue owner. If left out, the owner defaults to the user creating the issue. Optional

 

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body.  An abridged version of the JSON response object is shown below. Some arrays were left empty for brevity.

 

Response Property Description
id The Issue id
name The Issue name.
description The Issue description.
owner_id The id of the Issue owner.
deleted_at The ISO date string that when the Issue was deleted, if applicable
status The Issue status. Can have values "Open" , "Closed" or "Deleted"
guid Unique identifier for this issue. Used in routes to identify issue.
conclusion A description of the issue resolution that can be set when the issue is closed.
participants An array or Users. This will always at least include the issue owner.
invitations An array of objects describing people that have been invited to join the issue.
tag_list An array of Strings that users have used to tag this issue.
action_items An array of ActionItem objects associated with this Issue.
facts An array of Fact objects associated with this Issue.
uploads An array of Upload objects associated with this Issue.
owner The issue owner. Will always have a value.

Example Response:

{
    "id": 385,
    "name": "This is an issue name",
    "description": "This is a description",
    "created_at": "2015-04-01T11:25:39.017-05:00",
    "updated_at": "2015-04-01T11:25:39.091-05:00",
    "conference_number": null,
    "hash_key": "c1e378a68e711abea16d9b76cfd8a06b9abb8ed5",
    "owner_id": 71,
    "deleted_at": null,
    "status": "Open",
    "external_reference_id": null,
    "categories_updated_at": "2015-04-01T11:25:39.018-05:00",
    "messages_updated_at": "2015-04-01T11:25:39.091-05:00",
    "unknowns_updated_at": "2015-04-01T11:25:39.018-05:00",
    "facts_updated_at": "2015-04-01T11:25:39.018-05:00",
    "action_items_updated_at": "2015-04-01T11:25:39.018-05:00",
    "uploads_updated_at": "2015-04-01T11:25:39.018-05:00",
    "involvements_updated_at": "2015-04-01T11:25:39.018-05:00",
    "guid": "5b47b7b7-e102-44fe-ba18-cc531a7ebd2a",
    "conclusion": null,
    "webhook_url": "",
    "participants": [
        ...
    ],
    "invitations": [],
    "tag_list": [],
    "action_items": [],
    "facts": [],
    "uploads": [],
    "owner": {
        ...
    }
}

 

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.

 

Editing an Issue

HTTP Request

Method: PUT

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

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

Body Content: Can be a full Issue object or an abridged version with only the fields that are being edited. Attempting to edit a field that is not editable will usually just result in that field not being modified server-side. Note that once the "status" field has been changed to "Closed" that editing the issue no longer is possible.


{
    "id": "388",
    "name": "This is an issue name",
    "created_at": "2015-04-01T11:40:42.019-05:01",
    "updated_at": "2015-04-01T12:44:38.596-05:00",
    "description": "This is a description",
    "conference_number": null,
    "hash_key": "b17ed548adf6073554b4d1f5549aa357de5c3ec5",
    "owner_id": 71,
    "categories_updated_at": "2015-04-01T11:40:42.019-05:00",
    "deleted_at": null,
    "status": "Open",
    "external_reference_id": null,
    "messages_updated_at": "2015-04-01T12:44:38.596-05:00",
    "unknowns_updated_at": "2015-04-01T11:40:42.019-05:00",
    "facts_updated_at": "2015-04-01T11:40:42.019-05:00",
    "action_items_updated_at": "2015-04-01T11:40:42.019-05:00",
    "uploads_updated_at": "2015-04-01T11:40:42.019-05:00",
    "involvements_updated_at": "2015-04-01T11:40:42.054-05:00",
    "guid": "ae4790e8-8c13-4eedasdwe-96ff-0fc471f18ee2",
    "conclusion": null,
    "webhook_url": "",
    "participants": [
        {
            "id": 71,
            "email": "dillon.hodapp@kineticdata.com",
            "name": "Dillon Hodapp Admin",
            "created_at": "2014-07-02T15:39:55.039-05:00",
            "updated_at": "2015-04-01T08:26:58.513-05:00",
            "status": "Active",
            "deleted_at": null,
            "guid": "971c294f-49b7-4a05-a25f-733ce678449a",
            "time_zone": "Central Time (US & Canada)",
            "company": "Companydd",
            "phone": "555-555-5555",
            "title": "Title",
            "avatar_file_name": null,
            "avatar_content_type": null,
            "avatar_file_size": null,
            "avatar_updated_at": null
        }
    ],
    "tag_list": [
        "430"
    ],
    "owner": {
        "id": 71,
        "email": "dillon.hodapp@kineticdata.com",
        "name": "Dillon Hodapp Admin",
        "created_at": "2014-07-02T15:39:55.039-05:00",
        "updated_at": "2015-04-01T08:26:58.513-05:00",
        "status": "Active",
        "deleted_at": null,
        "guid": "971c294f-49b7-4a05-a25f-733ce678449a",
        "time_zone": "Central Time (US & Canada)",
        "company": "Companydd",
        "phone": "555-555-5555",
        "title": "Title",
        "avatar_file_name": null,
        "avatar_content_type": null,
        "avatar_file_size": null,
        "avatar_updated_at": null
    }
}

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 Issue.

 

Response Property Description
id The Issue id
name The Issue name.
description The Issue description.
owner_id The id of the Issue owner.
deleted_at The ISO date string that when the Issue was deleted, if applicable
status The Issue status. Can have values "Open" , "Closed" or "Deleted"
guid Unique identifier for this issue. Used in routes to identify issue.
conclusion A description of the issue resolution that can be set when the issue is closed.
participants An array or Users. This will always at least include the issue owner.
invitations An array of objects describing people that have been invited to join the issue.
tag_list An array of Strings that users have used to tag this issue.
action_items An array of ActionItem objects associated with this Issue.
facts An array of Fact objects associated with this Issue.
uploads An array of Upload objects associated with this Issue.
owner The issue owner. Will always have a value.

Example Response:


{
    "id": 388,
    "name": "This is an issue name",
    "created_at": "2015-04-01T11:40:42.019-05:00",
    "updated_at": "2015-04-01T13:03:08.287-05:00",
    "description": "This is a description",
    "conference_number": null,
    "hash_key": "b17ed548adf6073554b4d1f5549aa357de5c3ec5",
    "owner_id": 71,
    "categories_updated_at": "2015-04-01T11:40:42.019-05:00",
    "deleted_at": null,
    "status": "Open",
    "external_reference_id": null,
    "messages_updated_at": "2015-04-01T12:44:38.596-05:00",
    "unknowns_updated_at": "2015-04-01T11:40:42.019-05:00",
    "facts_updated_at": "2015-04-01T11:40:42.019-05:00",
    "action_items_updated_at": "2015-04-01T11:40:42.019-05:00",
    "uploads_updated_at": "2015-04-01T11:40:42.019-05:00",
    "involvements_updated_at": "2015-04-01T13:03:08.287-05:00",
    "guid": "ae4790e8-8c13-4eed-96ff-0fc471f18ee2",
    "conclusion": null,
    "webhook_url": "",
    "participants": [
        {
            "id": 71,
            "email": "dillon.hodapp@kineticdata.com",
            "name": "Dillon Hodapp Admin",
            "created_at": "2014-07-02T15:39:55.039-05:00",
            "updated_at": "2015-04-01T08:26:58.513-05:00",
            "status": "Active",
            "deleted_at": null,
            "guid": "971c294f-49b7-4a05-a25f-733ce678449a",
            "time_zone": "Central Time (US & Canada)",
            "company": "Companydd",
            "phone": "555-555-5555",
            "title": "Title",
            "avatar_file_name": null,
            "avatar_content_type": null,
            "avatar_file_size": null,
            "avatar_updated_at": null
        }
    ],
    "invitations": [],
    "tag_list": [
        "430"
    ],
    "action_items": [],
    "facts": [],
    "uploads": [],
    "owner": {
        "id": 71,
        "email": "dillon.hodapp@kineticdata.com",
        "name": "Dillon Hodapp Admin",
        "created_at": "2014-07-02T15:39:55.039-05:00",
        "updated_at": "2015-04-01T08:26:58.513-05:00",
        "status": "Active",
        "deleted_at": null,
        "guid": "971c294f-49b7-4a05-a25f-733ce678449a",
        "time_zone": "Central Time (US & Canada)",
        "company": "Companydd",
        "phone": "555-555-5555",
        "title": "Title",
        "avatar_file_name": null,
        "avatar_content_type": null,
        "avatar_file_size": null,
        "avatar_updated_at": null
    }
}
 

 

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.
422 Attribute can't be processed. Occurs when a field is malformed or when a field has been changed that can't be. For example, changing status from "Closed" to "Open" will result in a 422.
500 If there was an unexpected server error.

 


Fetching All Issues For Your User

Edit section

The API will return all issues that you are involved in.

HTTP Request

Edit section

Method: GET

URL: /api/v1/issues

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

Parameters

Edit section

 

Route Parameter Key Value Required / Optional
limit Specify number of items per page Optional
page Specify which page Optional

 

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 an array of Issues.

 

Example Response:

{
    "count": 112,
    "limit": 2,
    "offset": 0,
    "issues": [
        {
            ...
        },
        {
            ...
        }
    ]
}

 

A 200 response indicates a successful fetch. If your user is not involved in any issues then an empty array is returned else an array of Issues is returned.

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.
 

 

Querying for Issues

Issues are fetched by calling the 'search' route and using URL parameters to define what should be returned. Issues that match the search query AND that are linked to your user are returned.

HTTP Request

Method: GET

URL: /api/v1/issues/search

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

Parameters

 

Route Parameter Key Value Required / Optional
status Searches on the status field of an Issue. Can use "Open", "Closed" or "Deleted" for the value. Cannot be used in conjunction with the query parameter. Required if query parameter is not being used.
query Queries for issues that match a keyword Required if status parameter is not being use.
limit Specify number of items per page Optional
page Specify which page Optional

 

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 Issues.

 

Example Response:

{
    "count": 112,
    "limit": 2,
    "offset": 0,
    "issues": [
        {
            ...
        },
        {
            ...
        }
    ]
}

 

If a query is made that doesn't match any Issues then an empty array is returned. If nothing matches the 'status' URL parameter an empty array is also returned.

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.

 

Examples

1) Fetching all 'Closed' Issues using limit and page parameters:

https://kinetic.responsezone.io/api/...imit=10&page=2

2) Fetching all 'Closed' Issues:

https://kinetic.responsezone.io/api/...?status=Closed

3) Fetching all Issues that match the keyword 'the':

https://kinetic.responsezone.io/api/...arch?query=the

4) Fetching all Issues that match the keyword 'the' with limit and offset params:

https://kinetic.responsezone.io/api/...limit=5&page=0


Fetching an Issue

HTTP Request

Method: GET

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

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 a single Issue.

 

Example Response:


{
    "id": 385,
    "name": "This is an issue name",
    "description": "This is a description",
    "created_at": "2015-04-01T11:25:39.017-05:00",
    "updated_at": "2015-04-01T11:25:39.091-05:00",
    "conference_number": null,
    "hash_key": "c1e378a68e711abea16d9b76cfd8a06b9abb8ed5",
    "owner_id": 71,
    "deleted_at": null,
    "status": "Open",
    "external_reference_id": null,
    "categories_updated_at": "2015-04-01T11:25:39.018-05:00",
    "messages_updated_at": "2015-04-01T11:25:39.091-05:00",
    "unknowns_updated_at": "2015-04-01T11:25:39.018-05:00",
    "facts_updated_at": "2015-04-01T11:25:39.018-05:00",
    "action_items_updated_at": "2015-04-01T11:25:39.018-05:00",
    "uploads_updated_at": "2015-04-01T11:25:39.018-05:00",
    "involvements_updated_at": "2015-04-01T11:25:39.018-05:00",
    "guid": "5b47b7b7-e102-44fe-ba18-cc531a7ebd2a",
    "conclusion": null,
    "webhook_url": "",
    "participants": [
        ...
    ],
    "invitations": [],
    "tag_list": [],
    "action_items": [],
    "facts": [],
    "uploads": [],
    "owner": {
        ...
    }
}

 

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.
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.

Delete an Issue

Edit section

HTTP Request

Edit section

Method: DELETE

URL: /api/v1/issues/<issue_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.
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 Shared Issues

Edit section
Edit section

Fetches issues that are shared between the current user and a separate user.

HTTP Request

Edit section
Edit section

Method: GET

URL: /api/v1/users/<other_user_guid>/shared_issues

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

Parameters

Edit section

 

Route Parameter Key Value Required / Optional
limit Specify number of items per page Optional
page Specify which page Optional

 

HTTP Response

Edit section
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 an array of Issues.

 

Example Response:

{
    "count": 112,
    "limit": 2,
    "offset": 0,
    "issues": [
        {
            ...
        },
        {
            ...
        }
    ]
}

 

A 200 response indicates a successful fetch. If your user is not involved in any issues then an empty array is returned else an array of Issues is returned.

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
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.
 

 

Fetching Tags

Edit section

HTTP Request

Edit section

Method: GET

URL: /api/v1/tags

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 an array of tags.

 

Example Response:

[
    "tag1",
    "tag2",
    "tag3"
]

 

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.
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.