Issues
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
The API will return all issues that you are involved in.
HTTP Request
Method: GET
URL: /api/v1/issues
Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>
Parameters
| Route Parameter Key | Value | Required / Optional |
|---|---|---|
| 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": [
{
...
},
{
...
}
]
}
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
| 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
HTTP Request
Method: DELETE
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.
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
Fetching Shared Issues
Fetches issues that are shared between the current user and a separate user.
HTTP Request
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
| Route Parameter Key | Value | Required / Optional |
|---|---|---|
| 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": [
{
...
},
{
...
}
]
}
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
| 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
HTTP Request
Method: GET
URL: /api/v1/tags
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 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
| 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. |