API Introduction

The Null Autos API provides comprehensive programmatic access to the platform. Build custom integrations, automate device management, and integrate with your development workflow.

API Overview

Base URL

https://api.null.autos/v1

Authentication

All API requests require authentication using an API key:

curl https://api.null.autos/v1/devices \
  -H "Authorization: Bearer YOUR_API_KEY"

API Types

1. REST API: Complete CRUD operations for resources
2. WebSocket API: Real-time events and streaming
3. SDK: Pre-built clients for JavaScript/TypeScript and Python

REST API

Resources

Resource	Description
/devices	Virtual device management
/emulators	Emulator configuration and control
/snapshots	Device state snapshots
/images	Custom system images
/logs	Device and system logs
/metrics	Usage and performance metrics

HTTP Methods

• GET - Retrieve resource(s)
• POST - Create new resource
• PUT - Update existing resource
• PATCH - Partial update
• DELETE - Delete resource

Example: Create Device

curl -X POST https://api.null.autos/v1/devices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "androidVersion": "14.0",
    "deviceType": "phone",
    "name": "test-device",
    "hardware": {
      "cpus": 2,
      "memory": 2048,
      "gpu": true
    }
  }'

Response:

{
  "id": "dev_abc123xyz",
  "androidVersion": "14.0",
  "deviceType": "phone",
  "name": "test-device",
  "status": "creating",
  "hardware": {
    "cpus": 2,
    "memory": 2048,
    "gpu": true
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

WebSocket API

Real-time communication for events and streaming:

const ws = new WebSocket('wss://api.null.autos/v1/ws');

ws.on('open', () => {
  ws.send(JSON.stringify({
    type: 'authenticate',
    apiKey: 'YOUR_API_KEY',
  }));
});

ws.on('message', (data) => {
  const event = JSON.parse(data);
  console.log('Event:', event);
});

SDKs

JavaScript/TypeScript

npm install @null-autos/ctrl-sdk

import { CtrlClient } from '@null-autos/ctrl-sdk';

const ctrl = new CtrlClient({
  apiKey: process.env.CTRL_API_KEY,
});

const device = await ctrl.devices.create({
  androidVersion: '14.0',
  deviceType: 'phone',
});

Python

pip install null-autos-ctrl

from null_autos import CtrlClient

ctrl = CtrlClient(api_key='YOUR_API_KEY')
device = ctrl.devices.create(
    android_version='14.0',
    device_type='phone'
)

Response Format

Success Response

{
  "data": {
    "id": "dev_123",
    "name": "test-device"
  },
  "meta": {
    "requestId": "req_xyz789",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Response

{
  "error": {
    "code": "DEVICE_NOT_FOUND",
    "message": "Device with ID dev_123 not found",
    "details": {
      "deviceId": "dev_123"
    }
  },
  "meta": {
    "requestId": "req_xyz789",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request parameters
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Server error

Rate Limits

Tier	Requests/Minute	Devices	Burst
Free	60	5	100
Pro	300	50	500
Enterprise	1000	500	2000

Rate limit headers included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1610712000

Pagination

List endpoints support pagination:

curl "https://api.null.autos/v1/devices?page=2&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Filtering & Sorting

Filtering

curl "https://api.null.autos/v1/devices?status=running&deviceType=phone" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sorting

curl "https://api.null.autos/v1/devices?sort=-createdAt" \
  -H "Authorization: Bearer YOUR_API_KEY"

(Use - prefix for descending order)

Versioning

The API is versioned via URL path:

• Current: /v1
• Beta features: /v1beta

We maintain backwards compatibility within major versions.

Webhooks

Configure webhooks to receive events:

{
  "url": "https://your-app.com/webhooks/null-autos",
  "events": [
    "device.created",
    "device.ready",
    "device.deleted",
    "device.error"
  ],
  "secret": "your-webhook-secret"
}

Webhook payload:

{
  "event": "device.ready",
  "data": {
    "id": "dev_abc123",
    "status": "running"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "sha256=..."
}

Best Practices

1. Use SDKs: Pre-built clients handle auth, retries, and errors
2. Cache Responses: Reduce API calls with caching
3. Handle Errors: Implement retry logic with exponential backoff
4. Use Webhooks: More efficient than polling
5. Secure API Keys: Never commit keys to version control

Next Steps

• REST API Reference →
• WebSocket API →
• JavaScript SDK →
• Python SDK →

Support

• API Status: status.null.autos
• Support: support@null.autos
• API Changelog: docs.null.autos/changelog