Skip to content

bash-api.md

Latest commit

 

History

History
232 lines (186 loc) · 5.16 KB

bash-api.md

File metadata and controls

232 lines (186 loc) · 5.16 KB

Bash API Help

OpenAPI schema: openapi.yaml

DassieDrop exposes bash-friendly endpoints for automation, including workspace-aware sharing:

  • POST /api/share-text
  • POST /api/share-file
  • GET /api/workspaces
  • POST /api/workspaces

Share endpoints return a compact JSON payload with the generated short code, LAN share URL, and workspace metadata.

LAN link behavior is documented separately in lan-link-access.md.

Workspace Selection

Workspace-aware requests can target a workspace with any of these:

  • X-Workspace: <workspace-selector>
  • ?workspace=<workspace-selector>

Treat the workspace selector as an opaque string. Pass back the value the API gives you, exactly as-is.

The older X-Workspace-ID, X-Workspace-Slug, X-Workspace-Name, workspace_slug, and workspace_name aliases still work for compatibility, but they are no longer the public contract.

Protected workspaces can also use:

  • X-Workspace-Password: <workspace-password>

List workspaces:

curl -sS http://127.0.0.1:8000/api/workspaces

Create a workspace:

curl -sS \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"ops-desk","password":"vault"}' \
  http://127.0.0.1:8000/api/workspaces

Read state for a workspace by slug:

curl -sS \
  -H 'X-Workspace: ops-desk' \
  http://127.0.0.1:8000/api/state

Share Text

curl -sS \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "text": "hello from bash",
    "name": "CLI"
  }' \
  http://127.0.0.1:8000/api/share-text

Example response:

{
  "type": "text",
  "id": "4b6a6d7c8e9f0123",
  "short_code": "AbC123XyZ9",
  "share_path": "/s/AbC123XyZ9",
  "share_url": "http://127.0.0.1:8000/s/AbC123XyZ9",
  "hidden": false,
  "password_required": false,
  "created_at": 1714672800.0,
  "expires_at": 1714759200.0,
  "workspace_id": "default",
  "workspace_display_name": "Default",
  "workspace_slug": "default",
  "workspace_path": "/w/default",
  "workspace_url": "http://127.0.0.1:8000/w/default",
  "content": "hello from bash"
}

Hidden text example:

curl -sS \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "text": "secret note",
    "name": "CLI",
    "hidden": true,
    "password": "vault"
  }' \
  http://127.0.0.1:8000/api/share-text

Send text to a specific workspace:

curl -sS \
  -H 'Content-Type: application/json' \
  -H 'X-Workspace: ops-desk' \
  -X POST \
  -d '{
    "text": "hello from ops",
    "name": "CLI"
  }' \
  http://127.0.0.1:8000/api/share-text

Share File

curl -sS \
  -X POST \
  -F 'file=@./example.txt' \
  -F 'name=CLI' \
  http://127.0.0.1:8000/api/share-file

Example response:

{
  "type": "file",
  "id": "18f7d6c5b4a39281",
  "short_code": "Qw7N4LmP2x",
  "share_path": "/s/Qw7N4LmP2x",
  "share_url": "http://127.0.0.1:8000/s/Qw7N4LmP2x",
  "hidden": false,
  "password_required": false,
  "created_at": 1714672800.0,
  "expires_at": 1714759200.0,
  "workspace_id": "default",
  "workspace_display_name": "Default",
  "workspace_slug": "default",
  "workspace_path": "/w/default",
  "workspace_url": "http://127.0.0.1:8000/w/default",
  "name": "example.txt",
  "size": 42,
  "download_path": "/download/18f7d6c5b4a39281",
  "download_url": "http://127.0.0.1:8000/download/18f7d6c5b4a39281"
}

Hidden file example:

curl -sS \
  -X POST \
  -F 'file=@./secret.pdf' \
  -F 'name=CLI' \
  -F 'hidden=true' \
  -F 'password=vault' \
  http://127.0.0.1:8000/api/share-file

Upload a file into a specific workspace:

curl -sS \
  -H 'X-Workspace: ops-desk' \
  -X POST \
  -F 'file=@./example.txt' \
  -F 'name=CLI' \
  http://127.0.0.1:8000/api/share-file

Access Code

If DassieDrop is protected, the simplest bash option is to send the automation secret as X-API-Key. If API_KEY is configured, use that. Otherwise X-API-Key falls back to ACCESS_CODE:

curl -sS \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-api-key-or-access-code' \
  -X POST \
  -d '{"text":"hello again"}' \
  http://127.0.0.1:8000/api/share-text

You can do the same for file uploads:

curl -sS \
  -H 'X-API-Key: your-api-key-or-access-code' \
  -X POST \
  -F 'file=@./example.txt' \
  http://127.0.0.1:8000/api/share-file

And combine access code plus workspace targeting:

curl -sS \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-api-key-or-access-code' \
  -H 'X-Workspace: ops-desk' \
  -X POST \
  -d '{"text":"hello again"}' \
  http://127.0.0.1:8000/api/share-text

If you still want browser-style session auth from bash, you can log in first and reuse the session cookie:

curl -sS -c cookies.txt \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"code":"your-access-code"}' \
  http://127.0.0.1:8000/login

Then pass -b cookies.txt on later requests:

curl -sS -b cookies.txt \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"text":"hello again"}' \
  http://127.0.0.1:8000/api/share-text

X-API-Key is for authenticated API routes. LAN links under /s/{SHORT-CODE} do not use X-API-Key; use X-Access-Password there only when a password is required.