{ "openapi": "3.0.0", "info": { "title": "Agent API", "description": "Local HTTP API exposed by the Iconik Agent on the machine it runs on. A running Agent serves the specification for the version that is installed at http://localhost:6286/docs/json.", "version": "latest" }, "components": { "schemas": { "PingResponse": { "title": "Ping Response", "description": "Version of the Agent and the features it supports", "type": "object", "properties": { "version": { "description": "Version of the running Agent", "type": "string" }, "features": { "description": "Features this version of the Agent supports", "type": "array", "items": { "type": "string", "enum": [ "FORMAT_DOWNLOAD", "DOWNLOAD_BY_POST_REQUEST", "AUTO_LOGIN", "SHARES", "OPEN_IN_FCP", "UPLOAD_BY_POST_REQUEST", "DOWNLOAD_FILE_SET", "DOWNLOAD_VERSION", "DOWNLOAD_ALL_FORMATS", "LIST_DOWNLOADS", "LIST_UPLOADS", "DOWNLOAD_BY_FILE_ID", "DOWNLOAD_PLAYLISTS", "SHARE_TOKEN_AUTH", "OAUTH_LOOPBACK" ] } } }, "required": [ "version", "features" ] }, "DownloadRequestBody": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string" }, "format": { "type": "string" }, "outputPath": { "type": "string" } }, "required": [ "assetId", "format" ] } }, "collections": { "type": "array", "items": { "type": "object", "properties": { "collectionId": { "type": "string" }, "format": { "type": "string" } }, "required": [ "collectionId", "format" ] } }, "playlists": { "type": "array", "items": { "type": "object", "properties": { "playlistId": { "type": "string" }, "format": { "type": "string" } }, "required": [ "playlistId", "format" ] } }, "fileSets": { "type": "array", "items": { "type": "object", "properties": { "fileSetId": { "type": "string" }, "assetId": { "type": "string" } }, "required": [ "fileSetId", "assetId" ] } }, "assetVersions": { "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string" }, "assetId": { "type": "string" }, "format": { "type": "string" } }, "required": [ "versionId", "assetId", "format" ] } }, "files": { "type": "array", "items": { "type": "object", "properties": { "assetId": { "type": "string" }, "fileId": { "type": "string" }, "outputPath": { "type": "string" } }, "required": [ "assetId", "fileId" ] } } } }, "DownloadRequest": { "title": "Download Request", "description": "Request for a download. Contains one or more download items once resolved", "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "objectIdentity": { "$ref": "#/components/schemas/DownloadRequestIdentity" } }, "required": [ "id", "title", "objectIdentity" ] }, "DownloadRequests": { "title": "Download Requests", "description": "List of download requests", "type": "object", "properties": { "objects": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadRequest" } } }, "required": [ "objects" ] }, "DownloadItemStatus": { "title": "Download Item Status", "description": "The different statuses a download item can be in", "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "enqueued" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "resolving" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "active" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paused" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "completed" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "failed" ] }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "type", "code", "message" ] } ] }, "DownloadAssetItemIdentity": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asset" ] }, "id": { "type": "string" }, "formatId": { "type": "string" }, "outputPath": { "type": "string" } }, "required": [ "type", "id" ] }, "DownloadAssetFileSetItemIdentitySchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "fileSet" ] }, "id": { "type": "string" }, "assetId": { "type": "string" } }, "required": [ "type", "id", "assetId" ] }, "DownloadAssetVersionItemIdentity": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "assetVersion" ] }, "versionId": { "type": "string" }, "assetId": { "type": "string" }, "formatId": { "type": "string" } }, "required": [ "type", "versionId", "assetId" ] }, "DownloadAssetFileItemIdentity": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "assetFile" ] }, "assetId": { "type": "string" }, "id": { "type": "string" }, "outputPath": { "type": "string" } }, "required": [ "type", "assetId", "id" ] }, "DownloadCollectionItemIdentity": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "collection" ] }, "id": { "type": "string" }, "format": { "type": "string" } }, "required": [ "type", "id", "format" ] }, "DownloadPlaylistItemIdentity": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "playlist" ] }, "id": { "type": "string" }, "format": { "type": "string" } }, "required": [ "type", "id", "format" ] }, "DownloadItemIdentity": { "title": "Download Item Identity", "description": "Object to identify what to download", "anyOf": [ { "$ref": "#/components/schemas/DownloadAssetItemIdentity" }, { "$ref": "#/components/schemas/DownloadAssetFileSetItemIdentitySchema" }, { "$ref": "#/components/schemas/DownloadAssetVersionItemIdentity" }, { "$ref": "#/components/schemas/DownloadAssetFileItemIdentity" } ] }, "DownloadRequestIdentity": { "title": "Download Request Identity", "description": "Object to identify what was requested for download", "anyOf": [ { "$ref": "#/components/schemas/DownloadAssetItemIdentity" }, { "$ref": "#/components/schemas/DownloadAssetFileSetItemIdentitySchema" }, { "$ref": "#/components/schemas/DownloadAssetVersionItemIdentity" }, { "$ref": "#/components/schemas/DownloadAssetFileItemIdentity" }, { "$ref": "#/components/schemas/DownloadCollectionItemIdentity" }, { "$ref": "#/components/schemas/DownloadPlaylistItemIdentity" } ] }, "DownloadFileItem": { "title": "Download File Item", "description": "Represents one file being downloaded", "type": "object", "properties": { "fileId": { "type": "string" }, "fileName": { "type": "string" }, "fullPath": { "type": "string" }, "downloaded": { "type": "number" }, "size": { "type": "number" } }, "required": [ "fileId", "fileName", "fullPath", "downloaded" ] }, "DownloadItem": { "title": "Download Item", "description": "Download item that represents one download of an asset, version, file or file set", "type": "object", "properties": { "id": { "type": "string" }, "requestItemId": { "type": "string" }, "files": { "description": "List of files being downloaded as part of this item. An asset or file set can have multiple files associated with it.", "type": "array", "items": { "$ref": "#/components/schemas/DownloadFileItem" } }, "status": { "$ref": "#/components/schemas/DownloadItemStatus" }, "objectIdentity": { "$ref": "#/components/schemas/DownloadItemIdentity" } }, "required": [ "id", "requestItemId", "files", "status", "objectIdentity" ] }, "DownloadItems": { "title": "Download Items", "description": "List of download items", "type": "object", "properties": { "objects": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadItem" } } }, "required": [ "objects" ] }, "PatchDownloadItem": { "title": "Patch Download Item", "description": "Allows changing the status of a download. Only active and paused are allowed to update.", "type": "object", "properties": { "status": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "active" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "paused" ] } }, "required": [ "type" ] } ] } }, "required": [ "status" ] }, "AddDownloadRequestResponse": { "title": "Add Download Request", "description": "Response when adding a download request", "type": "array", "items": { "$ref": "#/components/schemas/DownloadRequest" } }, "UploadTargetAsset": { "anyOf": [ { "description": "Upload targets creating a new asset", "type": "object", "properties": { "type": { "type": "string", "enum": [ "newAsset" ] }, "assetId": { "description": "The asset id the file should be uploaded to. Leave this blank to create a new asset", "type": "string" } }, "required": [ "type" ] }, { "description": "Upload targets creating a new version of an existing asset", "type": "object", "properties": { "type": { "type": "string", "enum": [ "newVersion" ] }, "assetId": { "description": "The asset id the file should be uploaded to", "type": "string" }, "versionId": { "description": "The version id the file should be uploaded to. Leave this blank to create a new version", "type": "string" } }, "required": [ "type", "assetId" ] }, { "description": "Upload adds a format to an asset that already exists and is left in place", "type": "object", "properties": { "type": { "type": "string", "enum": [ "existingAsset" ] }, "assetId": { "description": "The asset id the file should be uploaded to", "type": "string" }, "fillsPlaceholder": { "description": "The asset is a placeholder that this upload turns into a regular asset", "type": "boolean" } }, "required": [ "type", "assetId" ] } ] }, "UploadRequestBody": { "type": "object", "properties": { "filePaths": { "type": "array", "items": { "description": "Array of file or folder paths to upload.", "type": "string" } }, "destinationStorageId": { "description": "The storage id to upload to. If no storage id is specified the current selection in the Agent will be used", "type": "string" }, "destinationCollectionId": { "description": "The collection id to upload to. If no collection id is specified the current selection in the Agent will be used", "type": "string" } }, "required": [ "filePaths" ] }, "UploadAssetItem": { "description": "Represents one file being uploaded", "type": "object", "properties": { "id": { "type": "string" }, "uploadRequestId": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "enum": [ "UPLOAD_FILE_FAILED" ] }, { "type": "string", "enum": [ "CLOSE_FILE_FAILED" ] }, { "type": "string", "enum": [ "GENERATE_KEYFRAMES_FAILED" ] } ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "state": { "type": "object", "properties": { "id": { "type": "string" }, "fileInfo": { "type": "object", "properties": { "targetPath": { "description": "Path to upload to including file name. This path is relative to the optional collection id specified for the upload. If only a file name is specified the file will be uploaded to the root of the collection. If a path is specified a collection structure replicating this path will be created in the root of the collection. This path will always be in posix format.", "type": "string" }, "size": { "description": "Size of the file in bytes", "type": "number" }, "mimeType": { "description": "Mime type of the file", "type": "string" } }, "required": [ "targetPath", "size", "mimeType" ] }, "target": { "$ref": "#/components/schemas/UploadTargetAsset", "description": "What the upload writes to: a new asset, a new version, or an asset that already exists" }, "targetAsset": { "$ref": "#/components/schemas/UploadTargetAsset", "deprecated": true, "description": "Deprecated, use target instead. Carries the same value and is only kept so integrations built before the rename keep working." }, "uploadKind": { "description": "What the upload creates on the asset, and the entities it has created so far", "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "file" ] }, "formatId": { "description": "The format the upload created", "type": "string" }, "fileSetId": { "description": "The file set the upload created", "type": "string" }, "fileId": { "description": "The file the bytes are written into", "type": "string" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "proxy" ] }, "proxyId": { "description": "The proxy the bytes are written into", "type": "string" } }, "required": [ "kind" ] } ] }, "formatId": { "deprecated": true, "description": "Deprecated, use uploadKind.formatId instead. Only a file upload has one.", "type": "string" }, "fileSetId": { "deprecated": true, "description": "Deprecated, use uploadKind.fileSetId instead. Only a file upload has one.", "type": "string" }, "fileId": { "deprecated": true, "description": "Deprecated, use uploadKind.fileId instead. A proxy upload writes into uploadKind.proxyId.", "type": "string" }, "status": { "type": "string", "enum": [ "WAITING", "UPLOADING", "COMPLETED", "COMPLETING", "PAUSED", "FAILED" ] }, "chunks": { "description": "List of chunks being uploaded and their status. This will only be available after the upload has started.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "status": { "type": "string", "enum": [ "WAITING", "UPLOADING", "COMPLETED", "FAILED" ] }, "start": { "type": "number" }, "size": { "type": "number" }, "uploaded": { "type": "number" } }, "required": [ "index", "status", "start", "size", "uploaded" ] } } }, "required": [ "id", "fileInfo", "target", "targetAsset", "uploadKind", "status" ] } }, "required": [ "id", "uploadRequestId", "state" ] }, "UploadAssetItems": { "type": "object", "properties": { "objects": { "type": "array", "items": { "$ref": "#/components/schemas/UploadAssetItem" } } }, "required": [ "objects" ] }, "UploadRequestItem": { "description": "Represents an upload request containing one or more UploadAssetItems", "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "directory" ] }, "title": { "type": "string" }, "assetIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "type", "title", "assetIds" ] }, "UploadRequestItems": { "type": "object", "properties": { "objects": { "type": "array", "items": { "$ref": "#/components/schemas/UploadRequestItem" } } }, "required": [ "objects" ] }, "UploadAssetItemPatch": { "description": "Object to patch an upload", "type": "object", "properties": { "state": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PAUSED", "UPLOADING" ] } }, "required": [ "status" ] } }, "required": [ "state" ] }, "AuthRequestBody": { "type": "object", "properties": { "auth": { "description": "Optional authentication token and app id. If not provided, the Agent will trigger the UI based login flow via the browser.", "type": "object", "properties": { "token": { "description": "The authentication token to use in the Agent", "type": "string" }, "appId": { "description": "The application id the token is for", "type": "string" } }, "required": [ "token", "appId" ] } } }, "LoginResponse": { "type": "object", "properties": { "userId": { "description": "Id of the user the Agent is logged in as", "type": "string" } }, "required": [ "userId" ] }, "OAuthSessionResult": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "error" ] }, "code": { "description": "The authorization code, when the status is complete", "type": "string" }, "error": { "description": "The OAuth error code, when the status is error", "type": "string" }, "error_description": { "type": "string" } }, "required": [ "status" ] } } }, "paths": { "/ping": { "get": { "summary": "Get the Agent version and the features it supports", "responses": { "200": { "description": "Version of the Agent and the features it supports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } } } } }, "/downloads": { "get": { "summary": "Get all downloads", "responses": { "200": { "description": "List of download items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadItems" } } } } } } }, "/downloads/{id}": { "get": { "summary": "Get a download by id", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Download item that represents one download of an asset, version, file or file set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadItem" } } } } } }, "patch": { "summary": "Change the status of a download", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchDownloadItem" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Download item that represents one download of an asset, version, file or file set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadItem" } } } } } } }, "/download-requests": { "get": { "summary": "Get all download requests", "responses": { "200": { "description": "List of download requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadRequests" } } } } } }, "post": { "summary": "Initiate a download", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadRequestBody" } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "open_in_fcp", "required": false, "description": "If set to 1 or true, the Agent will try to open the downloaded asset in FCP" }, { "schema": { "type": "string" }, "in": "query", "name": "resolve_on_local_isg", "required": false, "description": "If set to 1 or true, the Agent will try to resolve the download on the local ISG." }, { "schema": { "type": "string" }, "in": "header", "name": "app-id", "required": false, "description": "App ID for the auth token" }, { "schema": { "type": "string" }, "in": "header", "name": "iconik-host", "required": false, "description": "Host of the Iconik system the token belongs to, for example app.iconik.io. The Agent only uses the token headers below when this and app-id are both set." }, { "schema": { "type": "string" }, "in": "header", "name": "auth-token", "required": false, "description": "Optionally pass an auth token when initiating a download. This will try to log in the Agent using this token. If another user is already logged in the Agent will ask the user to confirm the switch of user." }, { "schema": { "type": "string" }, "in": "header", "name": "share-auth-token", "required": false, "description": "Share token to authenticate the Agent with, used instead of auth-token when downloading from a share." }, { "schema": { "type": "string" }, "in": "header", "name": "share-hash", "required": false, "description": "Hash of a public share to authenticate the Agent with, used instead of auth-token when downloading from a share." } ], "responses": { "200": { "description": "Response when adding a download request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDownloadRequestResponse" } } } } } } }, "/download-requests/{id}": { "get": { "summary": "Get a download request by id", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Request for a download. Contains one or more download items once resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadRequest" } } } } } }, "delete": { "summary": "Cancel a download request", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "No Content" } } } }, "/download-requests/{id}/downloads": { "get": { "summary": "Get all downloads for a download request", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "List of download items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadItems" } } } } } } }, "/upload": { "post": { "deprecated": true, "responses": { "200": { "description": "Default Response" } } } }, "/upload-requests": { "post": { "summary": "Enqueue an upload request.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequestBody" } } } }, "responses": { "200": { "description": "Default Response" } } }, "get": { "summary": "Get all upload requests", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequestItems" } } } } } } }, "/upload-requests/{id}": { "get": { "summary": "Get upload request by id", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Represents an upload request containing one or more UploadAssetItems", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequestItem" } } } } } } }, "/upload-requests/{id}/uploads": { "get": { "summary": "Get upload items for a request", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadAssetItems" } } } } } } }, "/uploads": { "get": { "summary": "Get all uploads", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadAssetItems" } } } } } } }, "/uploads/{id}": { "get": { "summary": "Get upload by id", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Represents one file being uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadAssetItem" } } } } } }, "patch": { "summary": "Patch an upload. Currently only supports updating the status.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Represents one file being uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadAssetItem" } } } } } }, "delete": { "summary": "Cancel an upload.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "No Content" } } } }, "/login": { "post": { "summary": "Log the Agent in", "description": "Logs the Agent in to Iconik. With an auth token and app id in the body the Agent authenticates as that user, asking for confirmation in the UI if another user is already logged in. With an empty body the Agent opens a browser window for the user to log in, unless it already has a valid session.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthRequestBody" } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } } } } }, "/logout": { "post": { "summary": "Log the Agent out", "description": "Logs the currently logged in user out of the Agent.", "responses": { "200": { "description": "Default Response" } } } }, "/oauth/sessions/{state}": { "get": { "summary": "Poll for the result of a sign-in redirect", "description": "A result is returned once and then forgotten. 404 until the browser has landed, and again once the result has expired.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "state", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthSessionResult" } } } } } }, "delete": { "summary": "Discard the result of a sign-in redirect", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "state", "required": true } ], "responses": { "204": { "description": "No Content" } } } } }, "servers": [ { "url": "http://localhost:6286", "description": "Agent local server" }, { "url": "https://localhost:6287", "description": "Agent local server over HTTPS, served on macOS only. Safari blocks plain HTTP to localhost, so use this one from Safari and from pages served over HTTPS." } ] }