Runrun.it API Documentation
How to authenticate to use the API
Every request to the API, should be sent with the authentication information, the app_key
and user_token
sent on the HEADER like:
curl "https://runrun.it/api/v1.0/users" -X GET \
-H "App-Key: f9c650c98eeb28e345e0a38a184d20cb" \
-H "User-Token: roBknmkPI0ALmwkRuC1q"
Whenever you send the incorrect information on app_key
or user_token
, the response is going to be 401 Unauthorized
.
The user_token
is per user and when you use this, you will perform actions on behalf of that user, on Runrun.it, it will appear that the user have done the action
How to obtain authentication information to use the API
API access is a premium feature only available for customers of certain paid accounts. To see which plans have API access check here. However developers with ideas for apps taking advantage of Runrun.it are always welcome to contact help@runrun.it about setting up a test account with API access.
- Go to your profile on Runrun.it
- Then click on
Generate
- Your
app_key
will be displayed with theuser_token
Data format
All responses will be valid JSON. Requests should be in JSON as well (although for most actions form-encoded data is accepted as well).
All dates will be in ISO 8601 format. The time-zones if specified, will take in account when doing date operations. Another thing to be mentioned is that you need to urlencode
your dates if it does contains special characters as +
to specify time-zones.
Monitoring
All calls to the API are recorded. Excessive use of the API will result in the offending app_key
being revoked to ensure quality of service for other users. If you anticipate a need
to issue a large number of API of calls please enter in contact with support beforehand.
Webhooks
Suported events
- "task:create" => Triggered when a task is created.
- "task:deliver" => Triggered when a task is delivered, that is, moved from an open stage to a closed stage.
- "task:reopen" => Triggered when a task is reopened, that is, when it is moved from a closed step to an open step.
- "task:move" => Triggered when a task is moved between stages without changing its state (open / closed).
- "task:add_manual_work_period" => Triggered when a user add hours manually to a task.
- "task:remove_manual_work_period" => Triggered when a user remove hours manually to a task.
- "task_assignment:play" => Triggered when a assignee click on play button.
- "task_assignment:pause" => Triggered when a assignee click on pause button.
Response
Here is an example of a response that will be sent:
{
"event": "task:deliver",
"happened_at": "2020-01-21 19:49:02 -0300",
"performer": { "id": "john-snow", "email": "john.snow@runrun.it" },
"data": {
"task": {
"id": 3302,
"board": { "id": 89 },
"board_stage": { "id": 48 },
"project": { "id": 66 },
"assignees": [
{ "id": "petey-cruiser", "email": "petey.cruiser@runrun.it" },
{ "id": "anna-mull", "email": "anna.mull@runrun.it" }
],
"user": { "id": "jack-doe", "email": "jack.doe@runrun.it" },
"url": "https://runrun.it/pt-BR/tasks/3302"
}
}
}
Subscribe/Unsubscribe
To subscribe or unsubscribe to a webhook just contact our support informing which events you are interested in listening to and the url that will be used.
Contacting API Support
If you have any trouble using the API, you can send an email to help@runrun.it.