{"openapi":"3.1.0","info":{"title":"Italic API","version":"2.0.0","description":"Recordings, devices, and notifications. Text syncs to Italic; audio stays on the client."},"servers":[{"url":"https://app.italic.com/api/v2"}],"tags":[{"name":"Recordings"},{"name":"Devices"},{"name":"API keys"},{"name":"Webhooks"},{"name":"Events"}],"paths":{"/recordings":{"get":{"operationId":"listRecordings","summary":"List recordings","tags":["Recordings"],"parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["clip","memo"]}},{"name":"q","in":"query","schema":{"type":"string","minLength":0,"maxLength":200}},{"name":"deviceId","in":"query","schema":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","transcribing","ready","no_speech","failed"]}},{"name":"from","in":"query","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"to","in":"query","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":0,"maxLength":1024}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"description":"Required permission: recordings: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/RecordingList"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createRecording","summary":"Create a recording","tags":["Recordings"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Reuse the same key and body when retrying a create request."}],"description":"Required permission: recordings:create.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRecording"}}}},"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/RecordingResult"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recordings/{id}":{"get":{"operationId":"getRecording","summary":"Get a recording","tags":["Recordings"],"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: recordings: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/RecordingResult"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"editRecording","summary":"Edit a recording","tags":["Recordings"],"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: recordings:write.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditRecording"}}}},"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/RecordingResult"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteRecording","summary":"Delete a recording","tags":["Recordings"],"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: recordings:delete.","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/Deleted"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/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"}}}}}}},"/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"}}}}}},"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"}}}}}}},"/api-keys":{"get":{"operationId":"listKeys","summary":"List API keys","tags":["API keys"],"parameters":[],"description":"Manage this in Settings → Integrations, or use a signed-in Italic account session. API keys cannot manage credentials or webhook destinations.","security":[{"accountSession":[]}],"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/KeyList"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createKey","summary":"Create an API key","tags":["API keys"],"parameters":[],"description":"Manage this in Settings → Integrations, or use a signed-in Italic account session. API keys cannot manage credentials or webhook destinations.","security":[{"accountSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKey"}}}},"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/KeyResult"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api-keys/{id}":{"delete":{"operationId":"deleteKey","summary":"Revoke an API key","tags":["API keys"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"}}],"description":"Manage this in Settings → Integrations, or use a signed-in Italic account session. API keys cannot manage credentials or webhook destinations.","security":[{"accountSession":[]}],"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/Deleted"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhooks","tags":["Webhooks"],"parameters":[],"description":"Manage this in Settings → Integrations, or use a signed-in Italic account session. API keys cannot manage credentials or webhook destinations.","security":[{"accountSession":[]}],"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/WebhookList"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createWebhook","summary":"Create a webhook","tags":["Webhooks"],"parameters":[],"description":"Manage this in Settings → Integrations, or use a signed-in Italic account session. API keys cannot manage credentials or webhook destinations.","security":[{"accountSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhook"}}}},"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/WebhookResult"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"}}],"description":"Manage this in Settings → Integrations, or use a signed-in Italic account session. API keys cannot manage credentials or webhook destinations.","security":[{"accountSession":[]}],"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/Deleted"}}}},"default":{"description":"Request failed. Errors include a stable code and a readable message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"operationId":"listEvents","summary":"List events","tags":["Events"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","minLength":0,"maxLength":32},"description":"Continue from nextCursor returned by the previous request. Omit to start at the beginning."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"description":"Required permission: events: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/EventList"}}}},"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 → Integrations."},"accountSession":{"type":"http","scheme":"bearer","description":"A signed-in Italic account session. An API key cannot manage access."}},"schemas":{"CreateRecording":{"type":"object","properties":{"type":{"type":"string","enum":["clip","memo"]},"title":{"type":"string","minLength":0,"maxLength":200},"transcript":{"type":"string","minLength":0,"maxLength":1000000},"summary":{"type":"string","minLength":0,"maxLength":1000000},"recordedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"externalId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},"audio":{"type":"array","items":{"type":"object","properties":{"clientId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},"fileId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"}},"required":["clientId","fileId"],"additionalProperties":false},"maxItems":20}},"required":["type"],"additionalProperties":false},"EditRecording":{"type":"object","properties":{"title":{"type":"string","minLength":0,"maxLength":200},"transcript":{"type":"string","minLength":0,"maxLength":1000000},"summary":{"type":"string","minLength":0,"maxLength":1000000},"pinned":{"type":"boolean"}},"required":[],"additionalProperties":false},"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},"CreateKey":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"scopes":{"type":"array","items":{"type":"string","enum":["recordings:create","recordings:read","recordings:write","recordings:delete","events:read","settings:read","settings:write"]},"minItems":1,"maxItems":7},"expiresInDays":{"type":"integer","minimum":1,"maximum":365}},"required":["name","scopes"],"additionalProperties":false},"CreateWebhook":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"events":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","enum":["recording.created","recording.updated","recording.deleted"]}}},"required":["url","events"],"additionalProperties":false},"Recording":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},"type":{"type":"string","enum":["clip","memo"]},"title":{"type":"string","minLength":0,"maxLength":200},"transcript":{"type":"string","minLength":0,"maxLength":1000000},"summary":{"type":"string","minLength":0,"maxLength":1000000},"recordedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"updatedAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","transcribing","ready","no_speech","failed"]},"pinned":{"type":"boolean"},"audio":{"type":"array","items":{"type":"object","properties":{"clientId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},"fileId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"}},"required":["clientId","fileId"],"additionalProperties":false}},"deviceId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},"externalId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"}},"required":["id","type","title","transcript","summary","recordedAt","updatedAt","revision","status","pinned","audio"]},"RecordingResult":{"type":"object","properties":{"recording":{"anyOf":[{"$ref":"#/components/schemas/Recording"},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","revision"],"additionalProperties":false}]},"replayed":{"type":"boolean"}},"required":["recording"]},"RecordingList":{"type":"object","properties":{"recordings":{"type":"array","items":{"$ref":"#/components/schemas/Recording"}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["recordings","nextCursor"]},"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}},"required":["id","name","model"],"additionalProperties":false},"DeviceList":{"type":"object","properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/Device"}}},"required":["devices"]},"SettingsResult":{"type":"object","properties":{"settings":{"$ref":"#/components/schemas/DeviceSettings"}},"required":["settings"]},"Key":{"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},"scopes":{"type":"array","items":{"type":"string","enum":["recordings:create","recordings:read","recordings:write","recordings:delete","events:read","settings:read","settings:write"]}},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"expiresAt":{"type":"integer","minimum":0,"maximum":9007199254740991},"revokedAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"lastUsedAt":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":[],"additionalProperties":false},"KeyList":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/Key"}}},"required":["keys"]},"KeyResult":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/Key"},"secret":{"type":"string"}},"required":["key","secret"]},"Webhook":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},"url":{"type":"string","minLength":0,"maxLength":2048},"events":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":[],"additionalProperties":false},"WebhookList":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["webhooks"]},"WebhookResult":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"secret":{"type":"string"}},"required":["webhook","secret"]},"Event":{"type":"object","properties":{"id":{"type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","enum":["recording.created","recording.updated","recording.deleted"]},"recordingId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},"revision":{"type":"integer","minimum":0,"maximum":9007199254740991},"createdAt":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","type","recordingId","revision","createdAt"],"additionalProperties":false},"EventList":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"nextCursor":{"type":"string"}},"required":["events","nextCursor"]},"Deleted":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},"deleted":{"type":"boolean"}},"required":["id","deleted"],"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"]}}}}