aidp-volumes

aidp-volumes — volume files & PAR transfers

Manage AIDP volumes and their contents — the staging area for larger/binary data, distinct from the workspace filesystem. Primary engine: the official Oracle aidp CLI volume group (same REST API + auth); oci raw-request is the fallback when the CLI isn't installed.

When to use

• "List volumes / what's in volume X", "upload/download a file to/from a volume", "make a directory in a volume", staging large or binary files.

CLI (preferred)

Per references/aidp-cli-map.md: volume list | get | create | list-files | make-dir | upload-file[-with-par] | download-file[-with-par] | delete-file | delete-dir. All take --instance-id <DATALAKE_OCID> --auth api_key --profile DEFAULT --region <r>.

# LIVE-VERIFIED: list needs BOTH catalogKey AND schemaKey
aidp volume list --catalog-key <cat> --schema-key <cat.schema> \
  --instance-id <DATALAKE_OCID> --auth api_key --profile DEFAULT --region us-ashburn-1
aidp volume get <key>        --instance-id <DATALAKE_OCID> --auth api_key --profile DEFAULT --region us-ashburn-1   # one volume
aidp volume list-files <key> --instance-id <DATALAKE_OCID> --auth api_key --profile DEFAULT --region us-ashburn-1   # browse files
aidp volume upload-file-with-par|download-file-with-par <key> ...                                                  # PAR transfer (binary-safe)
aidp volume make-dir|delete-file|delete-dir <key> ...

Mutating ops (create/make-dir/upload-file[-with-par]/delete-file/delete-dir): persist the body to .aidp/payloads/ and confirm with the user before running (see references/payloads.md).

Fallback (no CLI) — same REST + auth via oci raw-request against …/20240831/dataLakes/<DATALAKE_OCID>/… (auth ladder in references/oci-raw-request.md): GET /volumes?catalogKey=<cat>&schemaKey=<cat.schema> (both params required; a bare path / single param returns 400 InvalidParameter — the error names the missing key) · GET /volumes/<key> · files under GET /volumes/<key>/files · PAR upload/download via POST /volumes/<key>/actions/… then PUT/GET the bytes to the returned PAR URL · POST /volumes/<key>/actions/makeDir.

Verify-first (no-fabrication): the volumes routes are UNVERIFIED here — GET /volumes?catalogKey=… alone returned 400 (also needs schemaKey). Confirm the exact params with a live GET/volume list before any write/upload; record the working shape in references/rest-endpoint-map.md.

Live-verified 2026-06-10 on de-agent — correction: the route EXISTS (not removed). A bare GET …/volumes returns 400 InvalidParameter naming both missing keys — "query param schemaKey must not be null; query param catalogKey must not be null" — so listing volumes requires both catalogKey and schemaKey query params.

Workflow

1. Verify: aidp volume list --catalog-key <cat> --schema-key <cat.schema> (read back the required-param shape from the 400 if it errors).
2. Browse: list volumes → list-files <key>; get <key> for one volume's details.
3. Upload: upload-file-with-par; download: download-file-with-par (PAR bytes move directly to/from Object Storage, not through the JSON API).
4. Dirs: make-dir.
5. Confirm before destructive/overwrite operations.

Volume-object lifecycle (the volume itself, not its files)

Beyond file ops, the volume object has its own CRUD: aidp volume create | update | delete (REST POST /volumes · PUT /volumes/<key> · DELETE /volumes/<key>), plus directory ops make-dir | update-dir | delete-dir. Create body carries displayName, catalogKey, schemaKey (+ type/location) — confirm the exact fields with aidp help volume create / a live read before writing (routes need real catalog/schema keys, like list). Grants on a volume → aidp-roles-access (volume row). Persist create/update/delete bodies to .aidp/payloads/ and confirm first.

Notes

• PAR transfers are byte-accurate — they carry binary fine (wheels/jars/parquet) as well as text.
• Async (202): PAR-provisioning or dir actions may return 202 with an operation key — poll the async-ops endpoint until terminal (see aidp-observability / oci-raw-request.md).
• Volumes are the right home for big staging files before aidp-ingest-file-to-table.
• Workspace/catalog-scoped — confirm the workspace and catalog before listing.

References

• references/aidp-cli-map.md · references/payloads.md · references/oci-raw-request.md · references/no-mcp-rest-map.md · references/rest-endpoint-map.md · pairs with aidp-ingest-file-to-table, aidp-workspace-files