Runrun.it API Documentation
How to authenticate to use the API
Every request to the API should be sent with the correct authentication headers, app_key and user_token:
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 will be 401 Unauthorized.
The user_token is unique to each user and allows an agent to act on behalf of that user on Runrun.it.
The app_key identifies a whole account, and cannot be changed through the GUI.
How to access your API authentication keys
API access is a premium feature only available to customers of certain paid accounts. To see which plans include 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 Integration and Apps on Runrun.it
- Then look for "API and Webhooks" and click
Open
- Your
app_keywill be displayed next to 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 into account when doing date operations. Another thing to be mentioned is that you need to urlencode your dates if it does contain special characters like + 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 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 the quality of service for other users.
Webhooks
Manage Webhooks
On the API and Webhooks page, you can manage all webhooks on your account. To create or update a webhook, click on the + button, then select the event you want to listen to and enter the URL that will receive the HTTP POST payload. After creating a webhook, click Save to persist your changes.
To delete a webhook, click on the trash icon button and then "Delete".
Supported 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 adds hours manually to a task.task:remove_manual_work_period→ Triggered when a user removes hours manually to a task.task:change_time_worked→ Triggered when the total time worked on a task changes.task_assignment:play→ Triggered when an assignee clicks on the play button.task_assignment:pause→ Triggered when an assignee clicks on the 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 HTTP POST payload:
{
"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"
}
}
}
Contacting API Support
If you have any trouble using the API, you can email us at help@runrun.it.