Roborabbit API Reference
Roborabbit is a browser automation service.
- You design a browser automation in Roborabbit
- We turn it into an API
- You use the API to run the automation and get the output
https://api.roborabbit.com
Authentication
Roborabbit uses API keys to allow access to the API.
Roborabbit expects the API key to be included in all API requests to the server in a header that looks like the following:
Authorization: Bearer API_KEY
You can find your workspace API Keys in API Keys ↗.
All API requests on Roborabbit are scoped to a Workspace.
get | /v2/auth |
{
"message": "Authorized",
"workspace": "My Workspace"
}
Account
To check your account status at any time you can use this endpoint. It will respond with your quota levels and current usage levels. Usage resets at the start of every month.
get | /v1/account |
{
"created_at": "2022-12-01T03:48:23.228Z",
"uid": "x4p71qmnY1nD5obLdG",
"plan_name": "Roborabbit Automate",
"api_usage": 28,
"api_quota": 36000
}
Errors
The Roborabbit API uses the following status / error codes. The Roborabbit API rate limit is 30 requests per 10 seconds.
202 | Accepted -- Your request is has been accepted for processing |
200 | OK |
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
402 | Payment Required -- Your have run out of quota. |
404 | Not Found -- The specified request could not be found. |
429 | Too Many Requests -- Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Async
The Roborabbit API is asynchronous. When creating a new run, you POST a request, the API responds immediately with 202 Accepted and you either receive the generated result via webhook or via polling.
You can run as many concurrent tasks as you want, as long as you request them within the API rate limit.
Tasks
A Task is a set of instructions that make up a browser automation. Tasks are created and edited via the Roborabbit dashboard. The API can be used to list and retrieve Tasks.
To execute a Task, create a run.
get | /v1/tasks/:uid |
get | /v1/tasks |
The task object
Attributes
- uid stringThe unique ID for this object.
- name stringThe name of this task.
- viewport_width integerStarting viewport width.
- viewport_height integerStarting viewport height.
- steps arrayArray of steps that make up this task.
{
"created_at": "2022-12-01T03:48:43.728Z",
"name": "Elon Screenshot",
"uid": "851LyQMwvZw2lrXKpq",
"viewport_width": 1024,
"viewport_height": 768,
"steps": [
{
"action": "go",
"config": {
"url": "https://twitter.com/elonmusk"
},
"uid": "GNqV2ngBmly7O9dPRe"
},
{
"action": "take_screenshot",
"uid": "Km0k2XNbnlBA6Pplde"
}
]
}
Retrieve a task
Parameters
- uid stringrequiredThe task uid that you want to retrieve.
get | /v1/tasks/:uid |
fetch(`https://api.roborabbit.com/v1/tasks/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
List all tasks
Parameters
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v1/tasks |
fetch(`https://api.roborabbit.com/v1/tasks`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
Runs
A Run is an execution of a task. You can start a new Run via API.
Runs execute asynchronously. When you make a new POST request you will receive a 202 Accepted response. The Run will then begin to execute.
To get the status of a Run you can query the GET endpoint.
To be notified when a Run finishes you can use a webhook.
The run object
Attributes
- uid stringThe unique ID for this object.
- task stringThe uid of the parent task.
- video_url stringLink to a video of the task running.
- outputs arrayArray of data outputs from steps, if any
- steps arrayArray of task steps at the time of this run.
{
"created_at": "2022-12-06T04:34:15.238Z",
"video_url": "https://media.roborabbit.com/videos/oZwrg1DnX5qQM0v7Wq/2843a2b0a90c09b80d6d81f037854b5a3f33f2fa.mp4",
"uid": "5dDvA47kyWQ2N61w3R",
"task": "851LyQMwvZw2lrXKpq",
"steps": [
{
"action": "go",
"config": {
"url": "https://twitter.com/elonmusk"
},
"uid": "GNqV2ngBmly7O9dPRe"
},
{
"action": "take_screenshot",
"uid": "Km0k2XNbnlBA6Pplde",
"output": "https://media.roborabbit.com/screenshots/oZwrg1DnX5qQM0v7Wq/o2Wm9xgbkrEzpqDZ0Y/1.jpg"
}
],
"status": "finished",
"finished_in_seconds": 6,
"webhook_url": null,
"outputs": [],
"metadata": null
}
Create a run
Parameters
- steps arrayArray of step overrides. You must include the uid, action and a config object for each step you want to modify. If you don't add any overrides the step will run according to its default config. Set skip:true if you want to skip a step for this run.
- webhook_url stringA url to POST the full Run object to upon finishing.
- metadata stringAny metadata you need to store e.g. ID of a record in your DB.
post | /v1/tasks/:task_uid/runs |
//go to a different url
var data = {
"steps": [
{
"uid": "GNqV2ngBmly7O9dPRe",
"action": "go",
"config": {
"url": "https://twitter.com/apple"
}
}
]
}
fetch('https://api.roborabbit.com/v1/tasks/:task_uid/runs', {
method: 'POST',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
Retrieve a run
Parameters
- task_uid stringrequiredThe task uid.
- uid stringrequiredThe run uid that you want to retrieve.
get | /v1/tasks/:task_uid/runs/:uid |
fetch(`https://api.roborabbit.com/v1/tasks/${TASK_UID}/runs/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
List all runs
Parameters
- task_uid stringrequiredThe task uid.
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v1/tasks/:task_uid/runs |
fetch(`https://api.roborabbit.com/v1/tasks/${TASK_UID}/runs`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
Feeds
A Feed is a custom json feed of data from a task run.
You set up Feeds in the Roborabbit dashboard.
Feeds are different from Run outputs in that you can apply transformations to massage the data, if needed.
The feeds endpoint lists all custom feeds in a workspace.
get | /v1/feeds |
The feed object
Attributes
- uid stringThe unique ID for this object.
- name stringThe name of this feed.
- name stringThe description of this feed.
- last_run_at datetimeTimestamp of when this feed was last updated.
- url stringThe URL to the custom feed.
{
"name": "Bannerbear.com",
"uid": "X52gd36yKgye0Za1Ao",
"description": "Scraping the Bannerbear blog",
"last_run_at": "2023-09-14T06:39:24.036Z",
"url": "http://api.roborabbit.com/v1/tasks/bJZvOg2nY9nxP9yrzD/feeds/X52gd36yKgye0Za1Ao"
}
List all feeds
Parameters
- No parameters
get | /v1/feeds |
fetch(`https://api.roborabbit.com/v1/feeds`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})