# Artifacts Hub — HTTP API

Central storage for AI-generated artifacts (Markdown / HTML / any file).
Folders are plain directories and are created automatically on upload.
Files are scoped to your account; everything below operates within your own space.

## Authentication

Every request needs an API key issued from your account settings:

  Authorization: Bearer gbx_xxx

  curl -H "Authorization: Bearer gbx_xxx" https://gearbox.handsto.app/api/tree

Requests without a valid key (or browser session) get 401.

## Upload (main use case)

  curl -H "Authorization: Bearer gbx_xxx" -T report.md https://gearbox.handsto.app/api/files/myproject/

  -> 201 {"path":"myproject/report.md","view":"https://gearbox.handsto.app/api/view/myproject/report.md"}

- Endpoint: PUT /api/files/<folder>/<filename>  (raw request body = file content)
  A trailing "/" makes curl append the local filename automatically.
- Nested folders are fine: /api/files/projectA/reports/summary.md
- Name conflict -> auto-rename (report.md -> report-2.md). Always use the
  returned "path" / "view" as authoritative.
- To overwrite an existing file in place instead, add ?overwrite=1 :
    curl -T report.md "https://gearbox.handsto.app/api/files/myproject/report.md?overwrite=1"
  (works on /api/upload too). Without it, the original is never touched.

Multipart alternative (multiple files at once):

  curl -F files=@a.md -F files=@b.html "https://gearbox.handsto.app/api/upload?folder=myproject"

## Browse / read

  GET https://gearbox.handsto.app/api/tree          full folder/file tree as JSON (name, path, size, mtime)
  GET https://gearbox.handsto.app/api/raw/<path>    file content as-is (correct Content-Type)
  GET https://gearbox.handsto.app/api/raw/<path>?download=1   file as an attachment (download)
  GET https://gearbox.handsto.app/api/view/<path>   human-friendly view

## Download

  GET https://gearbox.handsto.app/api/zip/folder/<folder>       folder streamed as a .zip
  GET https://gearbox.handsto.app/api/zip?paths=a&paths=b/c      selected files/folders as one .zip

## Manage

  POST   https://gearbox.handsto.app/api/folders    JSON {"path":"a/b"}                create folder
  POST   https://gearbox.handsto.app/api/move       JSON {"from":"a/x.md","to":"b/"}   move into folder b/
                                  JSON {"from":"a/x.md","to":"a/y.md"}  rename
  DELETE https://gearbox.handsto.app/api/files/<path>     delete a file
  DELETE https://gearbox.handsto.app/api/folders/<path>   delete a folder recursively

Errors: 400 {"error":"..."} for invalid paths, 404 for missing files.
Human UI: https://gearbox.handsto.app/ (in a browser)