# API

## Authentication

All Datafy endpoints use a bearer token for authentication. Pass the token in the `Authorization` header:

```
Authorization: Bearer <token>
```

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=<sub-account-id>
  ```
* 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=<sub-account-id>,<sub-account-id>,...
  ?accounts=all
  ```

## Volume Lifecycle

## Create snapshot of a volume

> Create a snapshot of the specified volume<br>

```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":{"XDatafySubAccountIdHeader":{"in":"header","name":"X-Datafy-Sub-Account-Id","description":"DEPRECATED. Use the `accounts` query parameter with a single sub-account id\ninstead (e.g. `?accounts=<sub-account-id>`). Will be removed in a future release.\n","deprecated":true,"required":false,"schema":{"$ref":"#/components/schemas/SubAccountId"}},"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":{"SubAccountId":{"type":"string"},"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/XDatafySubAccountIdHeader"},{"$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<br>

```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":{"XDatafySubAccountIdHeader":{"in":"header","name":"X-Datafy-Sub-Account-Id","description":"DEPRECATED. Use the `accounts` query parameter with a single sub-account id\ninstead (e.g. `?accounts=<sub-account-id>`). Will be removed in a future release.\n","deprecated":true,"required":false,"schema":{"$ref":"#/components/schemas/SubAccountId"}},"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":{"SubAccountId":{"type":"string"},"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/XDatafySubAccountIdHeader"},{"$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<br>

```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":{"XDatafySubAccountIdHeader":{"in":"header","name":"X-Datafy-Sub-Account-Id","description":"DEPRECATED. Use the `accounts` query parameter with a single sub-account id\ninstead (e.g. `?accounts=<sub-account-id>`). Will be removed in a future release.\n","deprecated":true,"required":false,"schema":{"$ref":"#/components/schemas/SubAccountId"}},"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":{"SubAccountId":{"type":"string"},"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/XDatafySubAccountIdHeader"},{"$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<br>

```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":{"XDatafySubAccountIdHeader":{"in":"header","name":"X-Datafy-Sub-Account-Id","description":"DEPRECATED. Use the `accounts` query parameter with a single sub-account id\ninstead (e.g. `?accounts=<sub-account-id>`). Will be removed in a future release.\n","deprecated":true,"required":false,"schema":{"$ref":"#/components/schemas/SubAccountId"}},"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":{"SubAccountId":{"type":"string"},"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/XDatafySubAccountIdHeader"},{"$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":{"XDatafySubAccountIdHeader":{"in":"header","name":"X-Datafy-Sub-Account-Id","description":"DEPRECATED. Use the `accounts` query parameter with a single sub-account id\ninstead (e.g. `?accounts=<sub-account-id>`). Will be removed in a future release.\n","deprecated":true,"required":false,"schema":{"$ref":"#/components/schemas/SubAccountId"}},"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":{"SubAccountId":{"type":"string"},"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/XDatafySubAccountIdHeader"},{"$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: 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:

```
GET https://docs.datafy.io/resources/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.