> For the complete documentation index, see [llms.txt](https://docs.datafy.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datafy.io/resources/api.md). # API ## Authentication All Datafy endpoints use a bearer token for authentication. Pass the token in the `Authorization` header: ``` Authorization: Bearer ``` API tokens can be [generated](/set-up-and-installation/datafy-installation/token-generation.md) by an admin in the Datafy app and are scoped to the account from which they were created. ### Account tokens Account tokens are scoped to a single sub-account. Requests authenticated with an account token automatically target that account, no additional identifier is needed. ### Organization tokens Organization tokens are scoped to your organization and can target any sub-account within it. Generate an organization token the same way as an account token, by [generating a token](/set-up-and-installation/datafy-installation/token-generation.md) while logged in to an organization account in the Datafy app. Specify the target sub-account using the `accounts` query parameter: * For single-resource endpoints (e.g. create snapshot, attach, deactivate autoscaling) pass a single sub-account ID: ``` ?accounts= ``` * For list or aggregate endpoints pass a comma-separated list of sub-account IDs, or `all` to include every sub-account in your organization. The `accounts` parameter is required if using an organization token on list and aggregate endpoints. ``` ?accounts=,,... ?accounts=all ``` ## Volumes ## Volumes details > Retrieve a list of Datafy-managed volumes with their current size,\ > attachment, workload, autoscaling state, ongoing actions, and recent\ > utilization.\ > \ > Supports filtering, sorting, and pagination.
```json {"openapi":"3.0.0","info":{"title":"Datafy API","version":"1.0.0"},"tags":[{"name":"Volume-Lifecycle","description":"Endpoints for managing the lifecycle of storage volumes"}],"servers":[{"description":"Datafy API","url":"https://api.datafy.io"}],"security":[{"Authorizer":[]}],"components":{"securitySchemes":{"Authorizer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"AccountsQueryParam":{"in":"query","name":"accounts","description":"Target account(s) for the request.\nOn list/aggregate endpoints: a comma-separated list of sub-account ids, or \"all\" to\ninclude every sub-account of the calling org. Required for org users on these endpoints.\nOn single-resource endpoints: at most one sub-account id. Multiple values or \"all\"\nare silently ignored and the request runs against the caller's effective account.\n","required":false,"schema":{"type":"array","items":{"type":"string"}}}},"schemas":{"VolumeDetails":{"type":"object","description":"Datafy volume with current size, attachment, workload, autoscaling state, ongoing action, and recent utilization.","properties":{"accountId":{"type":"string","description":"Datafy account ID"},"volumeId":{"type":"string","description":"EBS volume identifier"},"underlyingVolumeIds":{"type":"array","items":{"type":"string"},"description":"Underlying Datafy-managed volumes"},"volumeName":{"type":"string","description":"Volume name (from the `Name` tag or discovered name)"},"diskType":{"type":"string","description":"EBS volume type (gp2, gp3, io1, io2)"},"originalSize":{"type":"integer","format":"int64","description":"Original provisioned size in bytes"},"currentSize":{"type":"integer","format":"int64","description":"Actual current size in bytes of the volume. Equals the actual size of the underlying datafy-managed volumes when autoscaling is active, and the originalSize otherwise."},"iops":{"type":"integer","description":"Provisioned IOPS"},"throughput":{"type":"integer","description":"Provisioned throughput in MiB/s"},"region":{"type":"string","description":"AWS region"},"availabilityZone":{"type":"string","description":"AWS availability zone"},"instanceId":{"type":"string","nullable":true,"description":"EC2 instance the volume is attached to. null when unattached."},"device":{"type":"string","nullable":true,"description":"Block device mapping on the attached instance (e.g. /dev/sdf). null when unattached."},"deleteOnTermination":{"type":"boolean","nullable":true,"description":"Whether the volume is deleted when the instance is terminated. null when unattached."},"isBootVolume":{"type":"boolean","nullable":true,"description":"Whether this is the root/boot volume of the instance. null when unattached."},"clusterName":{"type":"string","nullable":true,"description":"Kubernetes cluster name, when applicable."},"nodeGroupName":{"type":"string","nullable":true,"description":"EKS node group name, when applicable."},"autoScalingGroupName":{"type":"string","nullable":true,"description":"EC2 Auto Scaling group name, when applicable."},"autoscalingState":{"type":"string","enum":["on","off"],"description":"Whether Datafy is currently autoscaling the volume."},"eligible":{"type":"string","enum":["supported","pending setup","unsupported"],"description":"Whether the volume is eligible for autoscaling."},"ineligibleReason":{"type":"string","nullable":true,"description":"Reason for `pending setup` or `unsupported`. null when `supported`."},"excludedFromRules":{"type":"boolean","description":"Whether the volume is excluded from autoscaling rules."},"ongoingActionType":{"type":"string","nullable":true,"enum":["activate_autoscaling","deactivate_autoscaling","grow","shrink","modify"],"description":"Long-running action currently in progress. null when none."},"ongoingActionStatus":{"type":"string","nullable":true,"enum":["queued","in_progress"],"description":"Status of the ongoing action. null when no action is in progress."},"ongoingActionProgressPercent":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"Progress of the ongoing action (0-100). null when no action is in progress."},"usedBytes":{"type":"integer","format":"int64","nullable":true,"description":"Used space in bytes (most recent reading)."},"usedPercent":{"type":"number","format":"float","nullable":true,"description":"Used space as a percentage."},"lastReportedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the most recent utilization sample was reported."},"tags":{"type":"object","additionalProperties":{"type":"string"},"description":"Volume tags as a key/value map"}}}},"responses":{"BadRequestError":{"description":"Bad request"},"UnauthorizedError":{"description":"Authentication information is missing or invalid","headers":{"WWW_Authenticate":{"schema":{"type":"string"}}}}}},"paths":{"/api/v1/volumes/details":{"get":{"summary":"Volumes details","operationId":"listVolumesDetails","description":"Retrieve a list of Datafy-managed volumes with their current size,\nattachment, workload, autoscaling state, ongoing actions, and recent\nutilization.\n\nSupports filtering, sorting, and pagination.\n","tags":["Volume-Lifecycle"],"parameters":[{"$ref":"#/components/parameters/AccountsQueryParam"},{"in":"query","name":"filters","description":"Optional filters as a JSON array. Each filter is an object with\n`field`, `value`, and `op` properties.\n\nUse `?accounts=` to scope by account — there is no `accountId` filter.\n\nSupported filter fields and the operators for each:\n- `volumeId` — EBS volume ID. Operators: `equals`, `contains`, `in`.\n- `volumeName` — volume name. Operators: `equals`, `contains`, `in`.\n- `diskType` — EBS type (`gp2`, `gp3`, `io1`, `io2`). Operators: `equals`, `in`.\n- `originalSize` — provisioned size in bytes. Operators: `equals`, `greater than`, `greater than equal`, `less than`, `less than equal`.\n- `region` — AWS region. Operators: `equals`, `in`.\n- `availabilityZone` — AWS availability zone. Operators: `equals`, `in`.\n- `instanceId` — EC2 instance the volume is attached to. Operators: `equals`, `contains`, `in`.\n- `clusterName` — Kubernetes cluster name. Operators: `equals`, `in`.\n- `nodeGroupName` — Kubernetes node group name. Operators: `equals`, `in`.\n- `autoScalingGroupName` — EC2 Auto Scaling group name. Operators: `equals`, `in`.\n- `isBootVolume` — boolean (`true`/`false`). Operator: `equals`.\n- `excludedFromRules` — boolean (`true`/`false`). Operator: `equals`.\n- `autoscalingState` — one of `on`, `off`. Operator: `equals`. Comma-separated multi-value supported.\n- `eligible` — one of `supported`, `pending setup`, `unsupported`. Operator: `equals`. Comma-separated multi-value supported.\n- `tag:` — filter by tag key and value (e.g. `field: \"tag:Environment\"`, `value: \"prod\"`). Operators: `equals`, `contains`, `in`.\n","required":false,"schema":{"type":"array","items":{"type":"object","required":["field","value","op"],"properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["equals","contains","in","greater than","greater than equal","less than","less than equal"]}}}}},{"in":"query","name":"sortBy","description":"Sort specification with `field` (any top-level VolumeDetails field)\nand `ascending` (default true).\n","required":false,"schema":{"type":"object","properties":{"field":{"type":"string"},"ascending":{"type":"boolean","default":true}}}},{"in":"query","name":"limit","description":"Maximum number of records to return (max 1000)","required":false,"schema":{"type":"integer","format":"int32","minimum":0,"maximum":1000,"default":20}},{"in":"query","name":"offset","description":"Number of records to skip for pagination","required":false,"schema":{"type":"integer","format":"int32","minimum":0,"default":0}}],"responses":{"200":{"description":"volumes matching the requested filters","content":{"application/json":{"schema":{"type":"object","properties":{"volumes":{"type":"array","items":{"$ref":"#/components/schemas/VolumeDetails"}}}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` ## Volume Lifecycle ## Create snapshot of a volume > Create a snapshot of the specified volume
```json {"openapi":"3.0.0","info":{"title":"Datafy API","version":"1.0.0"},"tags":[{"name":"Snapshots","description":"Endpoints for snapshot management"},{"name":"Volume-Lifecycle","description":"Endpoints for managing the lifecycle of storage volumes"}],"servers":[{"description":"Datafy API","url":"https://api.datafy.io"}],"security":[{"Authorizer":[]}],"components":{"securitySchemes":{"Authorizer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"AccountsQueryParam":{"in":"query","name":"accounts","description":"Target account(s) for the request.\nOn list/aggregate endpoints: a comma-separated list of sub-account ids, or \"all\" to\ninclude every sub-account of the calling org. Required for org users on these endpoints.\nOn single-resource endpoints: at most one sub-account id. Multiple values or \"all\"\nare silently ignored and the request runs against the caller's effective account.\n","required":false,"schema":{"type":"array","items":{"type":"string"}}}},"schemas":{"VolumeId":{"type":"string"}},"responses":{"BadRequestError":{"description":"Bad request"},"UnauthorizedError":{"description":"Authentication information is missing or invalid","headers":{"WWW_Authenticate":{"schema":{"type":"string"}}}}}},"paths":{"/api/v1/volumes/{volumeId}/create-snapshot":{"post":{"summary":"Create snapshot of a volume","operationId":"createSnapshotCommand","description":"Create a snapshot of the specified volume\n","tags":["Volume-Lifecycle","Snapshots"],"parameters":[{"$ref":"#/components/parameters/AccountsQueryParam"},{"in":"path","name":"volumeId","required":true,"schema":{"$ref":"#/components/schemas/VolumeId"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"autoscalingOnly":{"type":"boolean","description":"Create snapshots only for volumes managed by Datafy","default":true},"useSourceVolume":{"readOnly":true,"type":"boolean","description":"Create the snapshot from the source volume (if it exists) (for internal use only)","default":false},"description":{"type":"string","description":"Description for the new snapshot"},"tags":{"type":"array","description":"Tags specifications for the new snapshot","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Sent create snapshot command","content":{"application/json":{"schema":{"type":"object","properties":{"datafySnapshotId":{"type":"string","description":"Datafy id of the snapshot"},"volumeId":{"type":"string","description":"Source volume id"},"status":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"volumeSizeGb":{"type":"integer","description":"Original size of the source volume"},"description":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` ## Create autoscaling volume from Datafy snapshots > Create new Datafy-managed autoscaling volume from Datafy snapshots
```json {"openapi":"3.0.0","info":{"title":"Datafy API","version":"1.0.0"},"tags":[{"name":"Snapshots","description":"Endpoints for snapshot management"},{"name":"Volume-Lifecycle","description":"Endpoints for managing the lifecycle of storage volumes"}],"servers":[{"description":"Datafy API","url":"https://api.datafy.io"}],"security":[{"Authorizer":[]}],"components":{"securitySchemes":{"Authorizer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"AccountsQueryParam":{"in":"query","name":"accounts","description":"Target account(s) for the request.\nOn list/aggregate endpoints: a comma-separated list of sub-account ids, or \"all\" to\ninclude every sub-account of the calling org. Required for org users on these endpoints.\nOn single-resource endpoints: at most one sub-account id. Multiple values or \"all\"\nare silently ignored and the request runs against the caller's effective account.\n","required":false,"schema":{"type":"array","items":{"type":"string"}}}},"schemas":{"CreateFromSnapshotsRequest":{"type":"object","properties":{"source":{"description":"Source specification for creating the autoscaling volume","oneOf":[{"type":"object","description":"Create from a single Datafy snapshot","required":["datafySnapshotId"],"properties":{"datafySnapshotId":{"type":"string"}}},{"type":"object","description":"Create from multiple AWS snapshot IDs in a region","required":["snapshotIds","region"],"properties":{"snapshotIds":{"type":"array","items":{"type":"string"}},"region":{"type":"string"}}}]},"volumeProperties":{"type":"object","required":["availabilityZone"],"properties":{"availabilityZone":{"type":"string"},"volumeIops":{"type":"integer","default":3000},"volumeThroughput":{"type":"integer","default":125},"tags":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}}},"required":["source","volumeProperties"]},"CreateFromSnapshotsResponse":{"type":"object","properties":{"volumeId":{"type":"string"},"volumeSizeGB":{"type":"integer"}}}},"responses":{"BadRequestError":{"description":"Bad request"},"UnauthorizedError":{"description":"Authentication information is missing or invalid","headers":{"WWW_Authenticate":{"schema":{"type":"string"}}}}}},"paths":{"/api/v1/volumes/create-from-snapshots":{"post":{"parameters":[{"$ref":"#/components/parameters/AccountsQueryParam"}],"summary":"Create autoscaling volume from Datafy snapshots","operationId":"createFromSnapshotsCommand","description":"Create new Datafy-managed autoscaling volume from Datafy snapshots\n","tags":["Volume-Lifecycle","Snapshots"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFromSnapshotsRequest"}}}},"responses":{"200":{"description":"Created autoscaling volume from Datafy snapshots","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFromSnapshotsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` ## Attach autoscaling volume > Attach an unattached Datafy-managed autoscaling volume to an instance with Datafy AutoScaler
```json {"openapi":"3.0.0","info":{"title":"Datafy API","version":"1.0.0"},"tags":[{"name":"Volume-Lifecycle","description":"Endpoints for managing the lifecycle of storage volumes"}],"servers":[{"description":"Datafy API","url":"https://api.datafy.io"}],"security":[{"Authorizer":[]}],"components":{"securitySchemes":{"Authorizer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"AccountsQueryParam":{"in":"query","name":"accounts","description":"Target account(s) for the request.\nOn list/aggregate endpoints: a comma-separated list of sub-account ids, or \"all\" to\ninclude every sub-account of the calling org. Required for org users on these endpoints.\nOn single-resource endpoints: at most one sub-account id. Multiple values or \"all\"\nare silently ignored and the request runs against the caller's effective account.\n","required":false,"schema":{"type":"array","items":{"type":"string"}}}},"schemas":{"VolumeId":{"type":"string"}},"responses":{"BadRequestError":{"description":"Bad request"},"UnauthorizedError":{"description":"Authentication information is missing or invalid","headers":{"WWW_Authenticate":{"schema":{"type":"string"}}}}}},"paths":{"/api/v1/volumes/{volumeId}/attach":{"post":{"summary":"Attach autoscaling volume","operationId":"attachCommand","description":"Attach an unattached Datafy-managed autoscaling volume to an instance with Datafy AutoScaler\n","tags":["Volume-Lifecycle"],"parameters":[{"$ref":"#/components/parameters/AccountsQueryParam"},{"in":"path","name":"volumeId","required":true,"schema":{"$ref":"#/components/schemas/VolumeId"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"instanceId":{"type":"string"},"deviceName":{"type":"string"},"deleteOnTermination":{"type":"boolean","description":"Indicates whether the volume is deleted on instance termination.\nThis flag is only effective when a Datafy agent is present on the instance.\n","default":false}},"required":["instanceId","deviceName"]}}}},"responses":{"200":{"description":"Attached autoscaling volume"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` ## Send deactivate autoscaling command > Send deactivate autoscaling command of a specific volume
```json {"openapi":"3.0.0","info":{"title":"Datafy API","version":"1.0.0"},"tags":[{"name":"Volume-Lifecycle","description":"Endpoints for managing the lifecycle of storage volumes"}],"servers":[{"description":"Datafy API","url":"https://api.datafy.io"}],"security":[{"Authorizer":[]}],"components":{"securitySchemes":{"Authorizer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"AccountsQueryParam":{"in":"query","name":"accounts","description":"Target account(s) for the request.\nOn list/aggregate endpoints: a comma-separated list of sub-account ids, or \"all\" to\ninclude every sub-account of the calling org. Required for org users on these endpoints.\nOn single-resource endpoints: at most one sub-account id. Multiple values or \"all\"\nare silently ignored and the request runs against the caller's effective account.\n","required":false,"schema":{"type":"array","items":{"type":"string"}}}},"schemas":{"VolumeId":{"type":"string"}},"responses":{"BadRequestError":{"description":"Bad request"},"UnauthorizedError":{"description":"Authentication information is missing or invalid","headers":{"WWW_Authenticate":{"schema":{"type":"string"}}}},"UnprocessableContentError":{"description":"Unprocessable content"}}},"paths":{"/api/v1/volumes/{volumeId}/deactivate-autoscaling":{"post":{"summary":"Send deactivate autoscaling command","operationId":"deactivateAutoscalingCommand","description":"Send deactivate autoscaling command of a specific volume\n","tags":["Volume-Lifecycle"],"parameters":[{"$ref":"#/components/parameters/AccountsQueryParam"},{"in":"path","name":"volumeId","required":true,"schema":{"$ref":"#/components/schemas/VolumeId"}}],"responses":{"200":{"description":"send deactivate autoscaling command"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/UnprocessableContentError"}}}}}} ``` ## Modify a volume > Modify the size of a specific volume ```json {"openapi":"3.0.0","info":{"title":"Datafy API","version":"1.0.0"},"tags":[{"name":"Volume-Lifecycle","description":"Endpoints for managing the lifecycle of storage volumes"}],"servers":[{"description":"Datafy API","url":"https://api.datafy.io"}],"security":[{"Authorizer":[]}],"components":{"securitySchemes":{"Authorizer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"AccountsQueryParam":{"in":"query","name":"accounts","description":"Target account(s) for the request.\nOn list/aggregate endpoints: a comma-separated list of sub-account ids, or \"all\" to\ninclude every sub-account of the calling org. Required for org users on these endpoints.\nOn single-resource endpoints: at most one sub-account id. Multiple values or \"all\"\nare silently ignored and the request runs against the caller's effective account.\n","required":false,"schema":{"type":"array","items":{"type":"string"}}}},"schemas":{"VolumeId":{"type":"string"}},"responses":{"BadRequestError":{"description":"Bad request"},"UnauthorizedError":{"description":"Authentication information is missing or invalid","headers":{"WWW_Authenticate":{"schema":{"type":"string"}}}}}},"paths":{"/api/v1/volumes/{volumeId}/modify":{"post":{"summary":"Modify a volume","operationId":"modifyCommand","description":"Modify the size of a specific volume","tags":["Volume-Lifecycle"],"parameters":[{"$ref":"#/components/parameters/AccountsQueryParam"},{"in":"path","name":"volumeId","required":true,"schema":{"$ref":"#/components/schemas/VolumeId"}}],"requestBody":{"description":"Desired values for modifying volume","content":{"application/json":{"schema":{"type":"object","description":"Desired values for modifying volume","properties":{"volumeSizeGB":{"type":"integer","description":"Desired size of volume, in GiB. Must be larger than current original size"},"expandFilesystem":{"type":"boolean","description":"Expand filesystem automatically after modifying","default":false},"autoscalingOnly":{"type":"boolean","description":"Modify only volumes managed by Datafy","default":true}},"required":["volumeSizeGb"]}}}},"responses":{"200":{"description":"send modify command"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.datafy.io/resources/api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.