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_keywill 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.
Request limit
There is a maximum limit of 100 requests per minute. If this limit is reached, it will be necessary to wait 1 minute to make new requests. In this case, the request response will return the http status code 429 with the following headers:
- "RateLimit-Limit" → request limit
- "RateLimit-Remaining" → remaining requests to reach the limit
- "RateLimit-Reset" → date when the limit will be restored
Excessive use of the API will result in the offending app_key being revoked to ensure quality of service for other users.
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:change_time_worked→ Triggered when the total time worked on a task changes.task_assignment:play→ Triggered when a assignee click on play button.task_assignment:pause→ Triggered when a assignee click on pause button.project:create→ Triggered when a project is created.project:change_time_worked→ Triggered when the total time worked on a project changes.client:create→ Triggered when a client is created.
Response
Here is an example of the payload 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.