API Overview

The UnboundBytes API is a RESTful API that provides programmatic access to all platform features. This page provides an overview of the API structure, conventions, and best practices.

Base URLs

Environment	URL
Production	`https://api.unboundbytes.com`
Staging	`https://api-staging.unboundbytes.com`

API Versioning

The API uses URL path versioning. All endpoints are prefixed with /v1/.

https://api.unboundbytes.com/v1/devices

Request Format

Headers

All requests should include the following headers:

Content-Type: application/json
Authorization: Bearer <token>

For HMAC authentication (agents), include:

x-ub-agent-id: agt_xxx
x-ub-tenant-id: ten_xxx
x-ub-timestamp: 2025-01-01T00:00:00Z
x-ub-signature: <hmac-sha256-signature>

Request Body

POST and PATCH requests should include a JSON body:

{
  "name": "my-deployment",
  "deviceId": "dev_xxx",
  "appId": "app_xxx"
}

Response Format

Success Response

{
  "success": true,
  "data": {
    "id": "dep_xxx",
    "name": "my-deployment",
    "status": "running"
  },
  "meta": {
    "timestamp": "2025-01-01T00:00:00Z",
    "requestId": "req_xxx"
  }
}

Collection Response

{
  "success": true,
  "data": [
    { "id": "dev_001", "hostname": "server-1" },
    { "id": "dev_002", "hostname": "server-2" }
  ],
  "meta": {
    "timestamp": "2025-01-01T00:00:00Z",
    "requestId": "req_xxx",
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 50,
      "totalPages": 3,
      "hasMore": true
    }
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "DEVICE_NOT_FOUND",
    "message": "Device with ID dev_xxx not found",
    "details": {
      "deviceId": "dev_xxx"
    }
  },
  "meta": {
    "timestamp": "2025-01-01T00:00:00Z",
    "requestId": "req_xxx"
  }
}

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`204`	No Content (successful deletion)
`400`	Bad Request (validation error)
`401`	Unauthorized (authentication required)
`403`	Forbidden (insufficient permissions)
`404`	Not Found
`409`	Conflict (resource already exists)
`422`	Unprocessable Entity (validation failed)
`429`	Too Many Requests (rate limited)
`500`	Internal Server Error
`503`	Service Unavailable

Rate Limiting

The API enforces rate limits to ensure fair usage:

Endpoint Type	Limit
Standard endpoints	100 requests/minute
Pairing endpoints	3-10 requests/minute
Heartbeat endpoint	60 requests/minute per device

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
Retry-After: 60

Pagination

List endpoints support pagination via query parameters:

GET /v1/devices?page=2&pageSize=20

Parameter	Description	Default	Max
`page`	Page number (1-indexed)	1	-
`pageSize`	Items per page	20	100

API Resources

Devices

Manage registered devices and their status. /v1/devices

Deployments

Deploy and manage applications. /v1/tenants/{tenantId}/deployments

Backups

Create and restore application backups. /v1/devices/{deviceId}/backups

Tunnels

Manage secure tunnels to devices. /v1/devices/{deviceId}/tunnels

Commands

Queue and execute commands on devices. /v1/devices/{deviceId}/commands

Pairing

Device pairing and activation flow. /v1/pairing/*

Next Steps

Authentication - Configure API authentication
API Explorer - Interactive API documentation
TypeScript SDK - Use the official SDK