https://sulala.aihttp://localhost:3000All device API requests require authentication via API key:
Authorization: Bearer sul_your_api_key_here
These endpoints are called by the device agent.
Send periodic heartbeat to keep device status as "online".
Request Headers:
Authorization: Bearer sul_your_api_key_here
Content-Type: application/json
Request Body:
{
"metadata": {
"os": "windows",
"version": "10.0.19041",
"hardware": "x64"
}
}
Response:
{
"success": true,
"status": "online"
}
Frequency: Recommended every 30-60 seconds
Poll for pending search requests from the cloud.
Request Headers:
Authorization: Bearer sul_your_api_key_here
Response:
{
"requests": [
{
"id": "clx789...",
"query": "example search",
"scope": ["files", "apps", "system"],
"createdAt": "2025-02-20T10:00:00Z"
}
]
}
Frequency: Recommended every 30 seconds (after heartbeat)
Report search results back to the cloud. This endpoint is called by the device after completing a search query.
Request Headers:
Authorization: Bearer sul_your_api_key_here
Content-Type: application/json
Request Body:
{
"queryId": "clx789...",
"query": "example search query",
"scope": ["files", "apps", "system"],
"results": {
"files": [
{
"path": "/path/to/file.txt",
"name": "file.txt",
"size": 1024,
"modified": "2025-02-20T10:00:00Z"
}
],
"apps": [
{
"name": "Chrome",
"path": "/Applications/Google Chrome.app",
"running": true
}
],
"system": {
"cpu": "50%",
"memory": "60%",
"disk": "40%"
}
},
"error": null
}
Response:
{
"success": true,
"queryId": "clx123...",
"status": "completed"
}
Error Response:
{
"success": false,
"queryId": "clx123...",
"status": "failed",
"error": "Error message"
}
Poll for pending file upload requests.
Request Headers:
Authorization: Bearer sul_your_api_key_here
Response:
{
"requests": [
{
"id": "clx456...",
"filePath": "/path/to/local/file.pdf",
"destination": "cloud",
"createdAt": "2025-02-20T10:00:00Z"
}
]
}
Upload a file to cloud storage.
Request Headers:
Authorization: Bearer sul_your_api_key_here
Content-Type: multipart/form-data
Request Body:
Form data:
- file: (binary file data)
- requestId: "clx456..."
Response:
{
"success": true,
"fileName": "file.pdf",
"fileUrl": "https://storage.sulala.ai/files/...",
"driveFile": {
"webViewLink": "https://drive.google.com/..."
},
"spacesFile": {
"publicUrl": "https://spaces.sulala.ai/..."
}
}
These endpoints are called from the dashboard/web interface.
List user's devices.
Authentication: User session (Clerk)
Response:
{
"devices": [
{
"id": "clx123...",
"name": "My Laptop",
"type": "desktop",
"platform": "macOS",
"status": "online",
"lastSeenAt": "2025-02-20T10:00:00Z",
"metadata": {},
"createdAt": "2025-02-20T09:00:00Z"
}
]
}
Register a new device.
Request:
{
"name": "My Laptop",
"type": "desktop",
"platform": "macOS",
"metadata": {}
}
Response:
{
"device": {
"id": "clx123...",
"name": "My Laptop",
"type": "desktop",
"platform": "macOS",
"status": "offline",
"createdAt": "2025-02-20T09:00:00Z"
},
"apiKey": "sul_abc123..."
}
Initiate a search across devices.
Request:
{
"query": "example search",
"scope": ["files", "apps", "system"],
"deviceIds": ["clx123..."]
}
Response:
{
"success": true,
"searchQueries": [
{
"id": "clx789...",
"deviceId": "clx123...",
"status": "pending"
}
],
"message": "Search queries created. Devices will process and return results."
}
Get search results.
Query Parameters:
queryId (optional): Specific query IDdeviceId (optional): Device IDstatus (optional): Filter by status (pending, completed, failed)Response:
{
"results": [
{
"id": "clx789...",
"device": {
"id": "clx123...",
"name": "My Laptop"
},
"query": "example search",
"scope": ["files"],
"results": {
"files": [...]
},
"status": "completed",
"createdAt": "2025-02-20T10:00:00Z",
"completedAt": "2025-02-20T10:00:05Z"
}
]
}
All endpoints may return these error responses:
{
"error": "Invalid or missing API key"
}
{
"error": "Validation error",
"message": "Specific validation error message"
}
{
"error": "Device not found"
}
{
"error": "Failed to process request"
}