# Devices

## List devices

`GET https://app.italic.com/api/v2/devices`

Required permission: settings:read.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Italic API",
    "version": "2.0.0",
    "description": "Recordings, devices, chat, tasks, workflows, connectors and notifications. Text syncs to Italic; audio stays on the client."
  },
  "servers": [
    {
      "url": "https://app.italic.com/api/v2"
    }
  ],
  "paths": {
    "/devices": {
      "get": {
        "operationId": "listDevices",
        "summary": "List devices",
        "tags": [
          "Devices"
        ],
        "parameters": [],
        "description": "Required permission: settings:read.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Writes without read permission return an ID and revision only.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier for troubleshooting."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceList"
                }
              }
            }
          },
          "default": {
            "description": "Request failed. Errors include a stable code and a readable message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → Developers → API keys."
      },
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "A signed-in Italic account session. An API key cannot create or revoke keys."
      }
    },
    "schemas": {
      "Device": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
          },
          "name": {
            "type": "string",
            "minLength": 0,
            "maxLength": 80
          },
          "model": {
            "type": "string",
            "minLength": 0,
            "maxLength": 80,
            "description": "The device type: `ring`, `glyph`, `dex` or `custom`."
          }
        },
        "required": [
          "id",
          "name",
          "model"
        ],
        "additionalProperties": false
      },
      "DeviceList": {
        "type": "object",
        "properties": {
          "devices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Device"
            }
          }
        },
        "required": [
          "devices"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100
              },
              "message": {
                "type": "string",
                "minLength": 0,
                "maxLength": 1000
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
```

## Create a custom device

`POST https://app.italic.com/api/v2/devices`

Required permission: settings:write. Adds a device of your own, such as a recorder or a script, to the account's devices. Italic does not connect to it: send what it records to POST /recordings with its `id` as `deviceId`. The apps list it under Custom in Devices, where the person can rename or remove it. An account can have 1,000 devices, removed ones included.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Italic API",
    "version": "2.0.0",
    "description": "Recordings, devices, chat, tasks, workflows, connectors and notifications. Text syncs to Italic; audio stays on the client."
  },
  "servers": [
    {
      "url": "https://app.italic.com/api/v2"
    }
  ],
  "paths": {
    "/devices": {
      "post": {
        "operationId": "createDevice",
        "summary": "Create a custom device",
        "tags": [
          "Devices"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Reuse the same key and body when retrying; the retry returns the first result with `replayed: true`. Keys are kept for 24 hours."
          }
        ],
        "description": "Required permission: settings:write. Adds a device of your own, such as a recorder or a script, to the account's devices. Italic does not connect to it: send what it records to POST /recordings with its `id` as `deviceId`. The apps list it under Custom in Devices, where the person can rename or remove it. An account can have 1,000 devices, removed ones included.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDevice"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Writes without read permission return an ID and revision only.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier for troubleshooting."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceResult"
                }
              }
            }
          },
          "default": {
            "description": "Request failed. Errors include a stable code and a readable message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → Developers → API keys."
      },
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "A signed-in Italic account session. An API key cannot create or revoke keys."
      }
    },
    "schemas": {
      "CreateDevice": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "What the apps call the device, such as Kitchen recorder. The person can rename it in the apps."
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "Device": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
          },
          "name": {
            "type": "string",
            "minLength": 0,
            "maxLength": 80
          },
          "model": {
            "type": "string",
            "minLength": 0,
            "maxLength": 80,
            "description": "The device type: `ring`, `glyph`, `dex` or `custom`."
          }
        },
        "required": [
          "id",
          "name",
          "model"
        ],
        "additionalProperties": false
      },
      "DeviceResult": {
        "type": "object",
        "properties": {
          "device": {
            "$ref": "#/components/schemas/Device"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "device"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100
              },
              "message": {
                "type": "string",
                "minLength": 0,
                "maxLength": 1000
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
```

## Get device settings

`GET https://app.italic.com/api/v2/devices/{id}/settings`

Required permission: settings:read.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Italic API",
    "version": "2.0.0",
    "description": "Recordings, devices, chat, tasks, workflows, connectors and notifications. Text syncs to Italic; audio stays on the client."
  },
  "servers": [
    {
      "url": "https://app.italic.com/api/v2"
    }
  ],
  "paths": {
    "/devices/{id}/settings": {
      "get": {
        "operationId": "getDeviceSettings",
        "summary": "Get device settings",
        "tags": [
          "Devices"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
            }
          }
        ],
        "description": "Required permission: settings:read.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Writes without read permission return an ID and revision only.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier for troubleshooting."
              },
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Use as If-Match for the next edit."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettingsResult"
                }
              }
            }
          },
          "default": {
            "description": "Request failed. Errors include a stable code and a readable message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → Developers → API keys."
      },
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "A signed-in Italic account session. An API key cannot create or revoke keys."
      }
    },
    "schemas": {
      "DeviceSettings": {
        "type": "object",
        "properties": {
          "inputs": {
            "type": "object",
            "properties": {
              "hold": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              },
              "doubleTap": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              },
              "tripleTap": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              },
              "recordButton": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              },
              "pushToTalk": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              },
              "appRecord": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              }
            },
            "required": [],
            "additionalProperties": false
          }
        },
        "required": [
          "inputs"
        ],
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100
              },
              "message": {
                "type": "string",
                "minLength": 0,
                "maxLength": 1000
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ]
      },
      "SettingsResult": {
        "type": "object",
        "properties": {
          "settings": {
            "$ref": "#/components/schemas/DeviceSettings"
          }
        },
        "required": [
          "settings"
        ]
      }
    }
  }
}
```

## Update device settings

`PATCH https://app.italic.com/api/v2/devices/{id}/settings`

Required permission: settings:write.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Italic API",
    "version": "2.0.0",
    "description": "Recordings, devices, chat, tasks, workflows, connectors and notifications. Text syncs to Italic; audio stays on the client."
  },
  "servers": [
    {
      "url": "https://app.italic.com/api/v2"
    }
  ],
  "paths": {
    "/devices/{id}/settings": {
      "patch": {
        "operationId": "editDeviceSettings",
        "summary": "Update device settings",
        "tags": [
          "Devices"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 256,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 0,
              "maxLength": 100
            },
            "description": "ETag from the last GET response. Prevents overwriting a newer edit."
          }
        ],
        "description": "Required permission: settings:write.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceSettings"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Writes without read permission return an ID and revision only.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Request identifier for troubleshooting."
              },
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "Use as If-Match for the next edit."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettingsResult"
                }
              }
            }
          },
          "default": {
            "description": "Request failed. Errors include a stable code and a readable message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Settings → Developers → API keys."
      },
      "accountSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "A signed-in Italic account session. An API key cannot create or revoke keys."
      }
    },
    "schemas": {
      "DeviceSettings": {
        "type": "object",
        "properties": {
          "inputs": {
            "type": "object",
            "properties": {
              "hold": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              },
              "doubleTap": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              },
              "tripleTap": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              },
              "recordButton": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              },
              "pushToTalk": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              },
              "appRecord": {
                "type": "string",
                "enum": [
                  "clip",
                  "memo"
                ]
              }
            },
            "required": [],
            "additionalProperties": false
          }
        },
        "required": [
          "inputs"
        ],
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100
              },
              "message": {
                "type": "string",
                "minLength": 0,
                "maxLength": 1000
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ]
      },
      "SettingsResult": {
        "type": "object",
        "properties": {
          "settings": {
            "$ref": "#/components/schemas/DeviceSettings"
          }
        },
        "required": [
          "settings"
        ]
      }
    }
  }
}
```