Version: 1.0.6

API Reference

Device Farm provides a REST API for programmatic access to devices, sessions, files, reservations, and test execution. Use this API to integrate Device Farm into your CI/CD pipelines, automation scripts, and custom tooling.

Base URL

https://api.rabbitqa.com/df/api

All endpoints below are relative to this base URL.

Authentication

Device Farm supports two authentication methods depending on the use case:

Bearer Token

Used for most API operations. Include the token in the Authorization header:

Authorization: Bearer YOUR_AUTH_TOKEN

API Key

Used specifically for Appium/WebDriver sessions and test event reporting. Include in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Manage your API keys from the Settings page or via the API Keys endpoints below.

Devices

List Devices

Retrieve available devices with optional filters.

GET /devices

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `ONLINE`, `OFFLINE`, `BUSY`
`type`	string	Filter by type: `ANDROID`, `IOS`
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)

Response:

{
  "data": [
    {
      "id": "device-uuid",
      "name": "Samsung Galaxy S24",
      "alias": "QA-Phone-1",
      "platform": "ANDROID",
      "osVersion": "14",
      "status": "ONLINE",
      "manufacturer": "Samsung",
      "model": "SM-S921B",
      "screenResolution": "1080x2340"
    }
  ],
  "total": 25,
  "page": 1,
  "limit": 20
}

Get Device

GET /devices/{deviceId}

Returns full details for a single device.

Update Device Alias

Set a custom display name for a device within your organization.

PUT /devices/{deviceId}/alias

{
  "alias": "QA-Phone-1"
}

Remove Device Alias

DELETE /devices/{deviceId}/alias

Sessions

List Sessions

GET /sessions

Query Parameters:

Parameter	Type	Description
`status`	string	`ACTIVE`, `ENDED`, `FAILED`
`deviceId`	string	Filter by device
`type`	string	`MANUAL`, `AUTOMATION`
`activeOnly`	boolean	Only active sessions
`page`	number	Page number
`limit`	number	Items per page

Response:

{
  "data": [
    {
      "id": "session-uuid",
      "deviceId": "device-uuid",
      "deviceName": "Samsung Galaxy S24",
      "type": "AUTOMATION",
      "status": "ACTIVE",
      "startedAt": "2025-06-15T10:00:00Z",
      "duration": 120000
    }
  ],
  "total": 50,
  "page": 1,
  "limit": 20
}

Get Session

GET /sessions/{sessionId}

Returns full session details including device info, test results, and duration.

Create Manual Session

Start a new manual testing session on a device.

POST /sessions

{
  "deviceId": "device-uuid"
}

Terminate Session

DELETE /sessions/{sessionId}

{
  "reason": "Test completed",
  "testResult": "PASSED",
  "testResultReason": "All 42 tests passed"
}

All fields are optional. The session ends immediately and the device becomes available.

Get Session Statistics

GET /sessions/stats

Returns aggregate statistics: total sessions, average duration, device usage breakdown.

Files

List Files

GET /files

Query Parameters:

Parameter	Type	Description
`page`	number	Page number
`limit`	number	Items per page

Response:

{
  "data": [
    {
      "id": "file-uuid",
      "filename": "app-debug.apk",
      "category": "APP",
      "status": "READY",
      "sizeBytes": 15728640,
      "uploadedAt": "2025-06-15T10:30:00Z",
      "tags": ["android", "debug"]
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 20
}

Get File

GET /files/{fileId}

Upload File

Device Farm uses presigned URLs for file uploads. See the Files - API Upload page for the complete 3-step upload flow with examples.

Summary:

Step	Method	Endpoint
1. Request URL	POST	`/files/presigned-upload`
2. Upload binary	PUT	`{presignedUrl}`
3. Confirm	POST	`/files/{fileId}/confirm`

For files over 100 MB, use the multipart upload flow documented on the same page.

Download File

Get a presigned download URL for a file.

GET /files/{fileId}/download

Response:

{
  "downloadUrl": "https://storage.example.com/presigned-download-url...",
  "expiresAt": "2025-06-15T11:00:00Z"
}

Delete File

DELETE /files/{fileId}

Reservations

List Reservations

GET /reservations

Query Parameters:

Parameter	Type	Description
`status`	string	`UPCOMING`, `ACTIVE`, `COMPLETED`, `CANCELLED`
`deviceId`	string	Filter by device
`myOnly`	boolean	Only your reservations
`page`	number	Page number
`limit`	number	Items per page

Get Reservation

GET /reservations/{reservationId}

Create Reservation

Book a device for a specific time slot.

POST /reservations

{
  "deviceId": "device-uuid",
  "startTime": "2025-06-16T09:00:00Z",
  "endTime": "2025-06-16T11:00:00Z",
  "purpose": "Regression testing for v2.1"
}

Update Reservation

Only upcoming (not yet started) reservations can be updated.

PUT /reservations/{reservationId}

{
  "startTime": "2025-06-16T10:00:00Z",
  "endTime": "2025-06-16T12:00:00Z",
  "purpose": "Updated: Smoke testing"
}

Cancel Reservation

DELETE /reservations/{reservationId}

{
  "reason": "No longer needed"
}

Check Device Availability

Check available time slots for a device on a specific date.

GET /reservations/availability/{deviceId}

Query Parameters:

Parameter	Type	Description
`date`	string	Date in `YYYY-MM-DD` format
`timezone`	string	IANA timezone (e.g. `Europe/Istanbul`)

Rejoin Reservation

Create a new session for an active reservation (e.g., after a disconnection).

POST /reservations/{reservationId}/rejoin

End Reservation Early

POST /reservations/{reservationId}/end

Test Events

Report test execution events from your automation framework. See the Test Event Integration page for complete examples with Java, Python, JavaScript, and cURL.

Report Event

POST /api/automation/sessions/{sessionId}/test-events

info

This endpoint uses the X-API-Key header for authentication, not Bearer token.

{
  "eventId": "uuid-v4",
  "type": "TEST_PASSED",
  "testName": "testLogin",
  "suiteName": "LoginTests",
  "duration": 1250,
  "error": {
    "message": "Assertion failed",
    "stackTrace": "..."
  }
}

Report Session Result

PUT /api/automation/sessions/{sessionId}/test-events/result

{
  "status": "passed",
  "reason": "All tests passed"
}

Marks the session with a final pass/fail status in the Dashboard.

Report Batch Events

POST /api/automation/sessions/{sessionId}/test-events/batch

{
  "events": [
    { "type": "TEST_STARTED", "testName": "test1", "suiteName": "Suite1" },
    { "type": "TEST_PASSED", "testName": "test1", "suiteName": "Suite1", "duration": 500 }
  ]
}

Get Events

GET /sessions/{sessionId}/test-events

Get Progress

GET /sessions/{sessionId}/test-events/progress

Response:

{
  "sessionId": "session-uuid",
  "total": 10,
  "completed": 5,
  "passed": 4,
  "failed": 1,
  "skipped": 0,
  "currentTest": "testPayment",
  "progress": 0.5,
  "estimatedRemainingSeconds": 120
}

API Keys

Manage API keys for Appium/WebDriver authentication and test event reporting.

List API Keys

GET /keys

Response:

{
  "data": [
    {
      "id": "key-uuid",
      "name": "CI Pipeline Key",
      "prefix": "df_auto_xxxx",
      "createdAt": "2025-06-01T00:00:00Z",
      "lastUsedAt": "2025-06-15T10:30:00Z"
    }
  ]
}

info

The full API key secret is only shown once at creation time. Store it securely.

Create API Key

POST /keys

{
  "name": "CI Pipeline Key"
}

Response:

{
  "id": "key-uuid",
  "name": "CI Pipeline Key",
  "key": "df_auto_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": "2025-06-15T10:00:00Z"
}

Save Your Key

The key field contains the full secret and is only returned once. Copy and store it in a secure location (e.g., CI/CD secrets, vault). It cannot be retrieved later.

Revoke API Key

DELETE /keys/{keyId}

Immediately invalidates the key. Any sessions or integrations using this key will stop working.

Error Responses

All endpoints return errors in a consistent format:

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Common Status Codes

Code	Meaning
200	Success
201	Created
400	Bad request (missing or invalid parameters)
401	Unauthorized (invalid or missing authentication)
403	Forbidden (no access to this resource)
404	Not found
413	Payload too large (file exceeds size limit)
422	Unprocessable (e.g., session not accepting events)
429	Too many requests (rate limited)
507	Insufficient storage (quota exceeded)

Rate Limits

API requests are rate limited per API key / auth token. If you exceed the limit, you'll receive a 429 Too Many Requests response. Wait and retry with exponential backoff.

Batch Events

Use the batch endpoint to report multiple test events in a single request, reducing the number of API calls.

Base URL​

Authentication​

Bearer Token​

API Key​

Devices​

List Devices​

Get Device​

Update Device Alias​

Remove Device Alias​

Sessions​

List Sessions​

Get Session​

Create Manual Session​

Terminate Session​

Get Session Statistics​

Files​

List Files​

Get File​

Upload File​

Download File​

Delete File​

Reservations​

List Reservations​

Get Reservation​

Create Reservation​

Update Reservation​

Cancel Reservation​

Check Device Availability​

Rejoin Reservation​

End Reservation Early​

Test Events​

Report Event​

Report Session Result​

Report Batch Events​

Get Events​

Get Progress​

API Keys​

List API Keys​

Create API Key​

Revoke API Key​

Error Responses​

Common Status Codes​

Rate Limits​

Base URL

Authentication

Bearer Token

API Key

Devices

List Devices

Get Device

Update Device Alias

Remove Device Alias

Sessions

List Sessions

Get Session

Create Manual Session

Terminate Session

Get Session Statistics

Files

List Files

Get File

Upload File

Download File

Delete File

Reservations

List Reservations

Get Reservation

Create Reservation

Update Reservation

Cancel Reservation

Check Device Availability

Rejoin Reservation

End Reservation Early

Test Events

Report Event

Report Session Result

Report Batch Events

Get Events

Get Progress

API Keys

List API Keys

Create API Key

Revoke API Key

Error Responses

Common Status Codes

Rate Limits