# Artifacts Hub — HTTP API

Central storage for AI-generated artifacts (Markdown / HTML / any file).
Folders are plain directories and are created automatically on upload.

Storage is organized into projects (shared workspaces with members). Plain
/api/... endpoints operate on your PERSONAL project. To work in a shared
project, list your projects and prefix every endpoint with /api/p/<pid>:

  GET https://sirius.stellarforce.cloud/api/projects
  -> {"projects":[{"pid":"...","name":"...","personal":true,"role":"owner"}]}

  # personal:              /api/tree, /api/files/..., /api/upload, ...
  # project <pid>:         /api/p/<pid>/tree, /api/p/<pid>/files/..., ...

Writes require the editor or owner role in that project (viewer = read-only).

## Authentication

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

  Authorization: Bearer gbx_xxx

  curl -H "Authorization: Bearer gbx_xxx" https://sirius.stellarforce.cloud/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://sirius.stellarforce.cloud/api/files/myproject/

  -> 201 {"path":"myproject/report.md","view":"https://sirius.stellarforce.cloud/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://sirius.stellarforce.cloud/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://sirius.stellarforce.cloud/api/upload?folder=myproject"

## Browse / read

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

## Download

  GET https://sirius.stellarforce.cloud/api/zip/folder/<folder>       folder streamed as a .zip
  GET https://sirius.stellarforce.cloud/api/zip?paths=a&paths=b/c      selected files/folders as one .zip

## Manage

  POST   https://sirius.stellarforce.cloud/api/folders    JSON {"path":"a/b"}                create folder
  POST   https://sirius.stellarforce.cloud/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://sirius.stellarforce.cloud/api/files/<path>     delete a file
  DELETE https://sirius.stellarforce.cloud/api/folders/<path>   delete a folder recursively

Every endpoint above also exists project-scoped, e.g.:

  curl -H "Authorization: Bearer gbx_xxx" -T report.md https://sirius.stellarforce.cloud/api/p/<pid>/files/docs/

## Tasks (per-project task / issue tracking)

Agents can file and update tasks in any project they can write to:

  GET    https://sirius.stellarforce.cloud/api/p/<pid>/tasks
  POST   https://sirius.stellarforce.cloud/api/p/<pid>/tasks
         JSON {"title":"...","note":"...","priority":"low|normal|high",
               "status":"todo|doing|done","dueDate":"YYYY-MM-DD","assigneeUid":"..."}
         (only "title" is required)
  GET    https://sirius.stellarforce.cloud/api/p/<pid>/tasks/<tid>
  PATCH  https://sirius.stellarforce.cloud/api/p/<pid>/tasks/<tid>      e.g. {"status":"done"}
  DELETE https://sirius.stellarforce.cloud/api/p/<pid>/tasks/<tid>

Task comments (progress reports, discussion):

  GET    https://sirius.stellarforce.cloud/api/p/<pid>/tasks/<tid>/comments
  POST   https://sirius.stellarforce.cloud/api/p/<pid>/tasks/<tid>/comments   JSON {"body":"..."}

## Artifact comments (discussion on an uploaded file)

  GET  https://sirius.stellarforce.cloud/api/p/<pid>/comments?path=<file path>
  POST https://sirius.stellarforce.cloud/api/p/<pid>/comments?path=<file path>   JSON {"body":"..."}

Errors: 400 {"error":"..."} for invalid paths, 401 no/invalid key,
403 not a member / viewer tried to write, 404 for missing files.
Human UI: https://sirius.stellarforce.cloud/ (in a browser)