> For the complete documentation index, see [llms.txt](https://help.aximo.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.aximo.autify.com/api-reference-ko/devices.md).
# Devices
List available mobile devices from AWS Device Farm, and register and manage your own local devices (BYOD). BYOD endpoints require the BYOD feature to be enabled for your organization and respond `404` when it is not.
## List available devices
> Returns mobile devices available for testing from AWS Device Farm.\
> Filter by platform or availability. Use a device's \`arn\` when creating\
> mobile sessions via \`POST /api/sessions\`.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Devices","description":"List available mobile devices from AWS Device Farm, and register and manage\nyour own local devices (BYOD). BYOD endpoints require the BYOD feature to be\nenabled for your organization and respond `404` when it is not.\n"}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"Device":{"type":"object","properties":{"arn":{"type":"string","description":"Encrypted device identifier token. Pass this value as `deviceArn` when creating sessions."},"name":{"type":"string"},"manufacturer":{"type":"string"},"model":{"type":"string"},"modelId":{"type":"string"},"platform":{"type":"string","enum":["ANDROID","IOS"]},"os":{"type":"string"},"formFactor":{"type":"string","enum":["PHONE","TABLET"]},"availability":{"type":"string"},"heapSize":{"type":"integer","nullable":true},"memory":{"type":"integer","nullable":true},"resolution":{"type":"object","nullable":true,"properties":{"width":{"type":"integer"},"height":{"type":"integer"}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/devices":{"get":{"operationId":"listDevices","summary":"List available devices","description":"Returns mobile devices available for testing from AWS Device Farm.\nFilter by platform or availability. Use a device's `arn` when creating\nmobile sessions via `POST /api/sessions`.\n","tags":["Devices"],"parameters":[{"name":"platform","in":"query","schema":{"type":"string","enum":["ANDROID","IOS"]},"description":"Filter devices by platform."},{"name":"availableOnly","in":"query","schema":{"type":"boolean","default":false},"description":"Only return devices currently available."}],"responses":{"200":{"description":"List of devices.","content":{"application/json":{"schema":{"type":"object","required":["devices"],"properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/Device"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Register a local device (BYOD)
> Registers your own device (a desktop machine or a locally connected phone)\
> for test execution and returns a device token. The token is shown \*\*only\
> once\*\* — store it securely. The on-device agent uses it to connect to the\
> Aximo gateway; the returned \`deviceId\` is what you pass as \`userDeviceId\`\
> when creating sessions or triggering runs.\
> \
> Requires the BYOD feature to be enabled for your organization; responds\
> \`404\` when it is not.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Devices","description":"List available mobile devices from AWS Device Farm, and register and manage\nyour own local devices (BYOD). BYOD endpoints require the BYOD feature to be\nenabled for your organization and respond `404` when it is not.\n"}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API key is not scoped to an organization, the user is banned, or the\nuser is no longer a member of the organization.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/devices/register":{"post":{"operationId":"registerDevice","summary":"Register a local device (BYOD)","description":"Registers your own device (a desktop machine or a locally connected phone)\nfor test execution and returns a device token. The token is shown **only\nonce** — store it securely. The on-device agent uses it to connect to the\nAximo gateway; the returned `deviceId` is what you pass as `userDeviceId`\nwhen creating sessions or triggering runs.\n\nRequires the BYOD feature to be enabled for your organization; responds\n`404` when it is not.\n","tags":["Devices"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","platform"],"properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the device."},"platform":{"type":"string","enum":["windows","macos","linux","ios","android"]},"os":{"type":"string","maxLength":256,"description":"OS version string (informational)."}}}}}},"responses":{"201":{"description":"Device registered.","content":{"application/json":{"schema":{"type":"object","required":["deviceId","deviceToken"],"properties":{"deviceId":{"type":"string","format":"uuid","description":"Pass this value as `userDeviceId` when creating sessions or triggering runs."},"deviceToken":{"type":"string","description":"Device token for the on-device agent. Shown only once."}}}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"BYOD is not enabled for the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## List registered local devices
> Returns local devices (BYOD) registered by the authenticated user (the\
> API key's owner). Use a device's \`id\` as \`userDeviceId\` when creating\
> sessions or triggering runs.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Devices","description":"List available mobile devices from AWS Device Farm, and register and manage\nyour own local devices (BYOD). BYOD endpoints require the BYOD feature to be\nenabled for your organization and respond `404` when it is not.\n"}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"UserDevice":{"type":"object","required":["id","name","platform","status","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Pass this value as `userDeviceId` when creating sessions or triggering runs."},"name":{"type":"string"},"platform":{"type":"string","enum":["windows","macos","linux","ios","android"]},"os":{"type":"string","nullable":true,"description":"OS version string reported at registration."},"status":{"type":"string","enum":["online","offline"],"description":"Last known connection status of the device agent."},"lastSeenAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API key is not scoped to an organization, the user is banned, or the\nuser is no longer a member of the organization.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/devices/user":{"get":{"operationId":"listUserDevices","summary":"List registered local devices","description":"Returns local devices (BYOD) registered by the authenticated user (the\nAPI key's owner). Use a device's `id` as `userDeviceId` when creating\nsessions or triggering runs.\n","tags":["Devices"],"responses":{"200":{"description":"List of registered devices.","content":{"application/json":{"schema":{"type":"object","required":["devices"],"properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/UserDevice"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"BYOD is not enabled for the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Unregister a local device
> Removes a registered local device. Only devices registered by the\
> authenticated user can be removed. The device's token stops working\
> immediately.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Devices","description":"List available mobile devices from AWS Device Farm, and register and manage\nyour own local devices (BYOD). BYOD endpoints require the BYOD feature to be\nenabled for your organization and respond `404` when it is not.\n"}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API key is not scoped to an organization, the user is banned, or the\nuser is no longer a member of the organization.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/devices/user/{deviceId}":{"delete":{"operationId":"deleteUserDevice","summary":"Unregister a local device","description":"Removes a registered local device. Only devices registered by the\nauthenticated user can be removed. The device's token stops working\nimmediately.\n","tags":["Devices"],"parameters":[{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID returned by `POST /api/devices/register`."}],"responses":{"200":{"description":"Device removed.","content":{"application/json":{"schema":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Invalid device ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Device not found, or BYOD is not enabled for the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Get device agent manifest
> Returns the current version and checksums of the on-device agent assets.\
> The aximo CLI uses this to decide whether its cached agent files are up\
> to date before downloading them via \`GET /api/devices/agent/{file}\`.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Devices","description":"List available mobile devices from AWS Device Farm, and register and manage\nyour own local devices (BYOD). BYOD endpoints require the BYOD feature to be\nenabled for your organization and respond `404` when it is not.\n"}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API key is not scoped to an organization, the user is banned, or the\nuser is no longer a member of the organization.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"paths":{"/api/devices/agent/manifest":{"get":{"operationId":"getAgentManifest","summary":"Get device agent manifest","description":"Returns the current version and checksums of the on-device agent assets.\nThe aximo CLI uses this to decide whether its cached agent files are up\nto date before downloading them via `GET /api/devices/agent/{file}`.\n","tags":["Devices"],"responses":{"200":{"description":"Agent manifest.","content":{"application/json":{"schema":{"type":"object","required":["manifestVersion","version","script","requirements"],"properties":{"manifestVersion":{"type":"integer"},"version":{"type":"string","description":"Short hash identifying this agent build."},"script":{"type":"object","required":["sha256","size"],"properties":{"sha256":{"type":"string"},"size":{"type":"integer","description":"Size in bytes."}}},"requirements":{"type":"object","required":["sha256","size"],"properties":{"sha256":{"type":"string"},"size":{"type":"integer","description":"Size in bytes."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"BYOD is not enabled for the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Download a device agent asset
> Downloads one of the on-device agent files listed in the manifest.\
> Verify the response against the \`sha256\` from\
> \`GET /api/devices/agent/manifest\`.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Devices","description":"List available mobile devices from AWS Device Farm, and register and manage\nyour own local devices (BYOD). BYOD endpoints require the BYOD feature to be\nenabled for your organization and respond `404` when it is not.\n"}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API key is not scoped to an organization, the user is banned, or the\nuser is no longer a member of the organization.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"paths":{"/api/devices/agent/{file}":{"get":{"operationId":"downloadAgentAsset","summary":"Download a device agent asset","description":"Downloads one of the on-device agent files listed in the manifest.\nVerify the response against the `sha256` from\n`GET /api/devices/agent/manifest`.\n","tags":["Devices"],"parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string","enum":["remote.py","requirements.txt"]},"description":"Agent asset file name."}],"responses":{"200":{"description":"Asset content (`text/x-python` for `remote.py`, `text/plain; charset=utf-8` for `requirements.txt`).","content":{"text/x-python":{"schema":{"type":"string"}},"text/plain; charset=utf-8":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Unknown agent asset, or BYOD is not enabled for the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Download an app binary for a local device
> Downloads a previously uploaded app binary (APK/IPA) so the on-device\
> aximo CLI can install it on a local BYOD device. In cloud environments\
> the response is a \`302\` redirect to a short-lived download URL; follow\
> redirects and expect a binary body either way.
```json
{"openapi":"3.0.3","info":{"title":"Aximo API","version":"1.0.0"},"tags":[{"name":"Devices","description":"List available mobile devices from AWS Device Farm, and register and manage\nyour own local devices (BYOD). BYOD endpoints require the BYOD feature to be\nenabled for your organization and respond `404` when it is not.\n"}],"servers":[{"url":"/","description":"Current environment"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Organization API key generated from Settings → API Keys."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API key is not scoped to an organization, the user is banned, or the\nuser is no longer a member of the organization.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded — e.g. the daily session limit was reached for the\norganization, or too many API requests were sent in a short window\n(retry after the number of seconds in the `Retry-After` header).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/devices/apps/{uploadId}/download":{"get":{"operationId":"downloadDeviceApp","summary":"Download an app binary for a local device","description":"Downloads a previously uploaded app binary (APK/IPA) so the on-device\naximo CLI can install it on a local BYOD device. In cloud environments\nthe response is a `302` redirect to a short-lived download URL; follow\nredirects and expect a binary body either way.\n","tags":["Devices"],"parameters":[{"name":"uploadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID returned by `POST /api/uploads`."}],"responses":{"200":{"description":"App binary streamed from storage.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"302":{"description":"Redirect to a short-lived download URL.","headers":{"Location":{"schema":{"type":"string"},"description":"Presigned URL the binary can be fetched from."}}},"400":{"description":"Invalid upload ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"App file not found (no binary stored for this upload, or it belongs\nto another organization), or BYOD is not enabled for the organization.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```