athena-python-docx 0.20.0__tar.gz → 0.21.0__tar.gz

{athena_python_docx-0.20.0 → athena_python_docx-0.21.0}/CLAUDE.md

@@ -67,11 +67,7 @@ These standard python-docx members don't apply to a Superdoc-backed SDK:
 ### Phase-3b upstream-blocked surface
 
 These are *shipped at the surface* but partially or fully no-op at
-runtime, pending SuperDoc SDK changes outside this repo. The
-upstream constraints have been verified against
-[SuperDoc's published docs](https://docs.superdoc.dev/document-api/reference/styles/apply)
-and the bundled TypeScript types in
-`node_modules/@superdoc-dev/sdk/dist/generated/client.d.ts`. See
+runtime, pending DOCX Studio backend changes. See
 `docx-studio/PYTHON_DOCX_PARITY_GAPS.md` § *What unblocks the
 remaining work* for the exact wire-op shape needed to unblock each.
 
@@ -132,16 +128,15 @@ not file-backed. Each is documented in the relevant docstring.
 
 - **`Document.create(name=, base_url=, api_key=, parent_folder_id=, workspace_id=, docx=, agora_base_url=)`**
   classmethod. Stock python-docx returns a blank in-memory document
-  for `Document(None)`; we can't fabricate a SuperDocument asset
+  for `Document(None)`; we can't fabricate a Word document asset
   client-side, so net-new asset creation is a separate factory that
   hits `POST {base_url}/docs/empty`. The constructor positional-arg
   shape (`Document(asset_id)`) is preserved for parity.
   - **`docx=path`** mirrors the upstream `Document(docx="template.docx")`
-    constructor kwarg: when provided, the local `.docx` is uploaded to
-    agora's `/api/super-docs/create-from-upload` and used as the seed
-    for the new SuperDocument. The bytes are mirrored to S3 server-side
-    so subsequent template-asset reuse is fast. Without `docx=`, the
-    default Athena template is applied as today.
+    constructor kwarg: when provided, the SDK creates a normal Word
+    document asset through Agora's docx-studio bridge, then imports the
+    local `.docx` into that asset. Without `docx=`, the default Athena
+    template is applied as today.
   - **`agora_base_url=`** is a transport-detail kwarg only required when
     the SDK can't derive the agora host from `base_url` (or from
     `$ATHENA_AGORA_BASE_URL`). The default substitution rule replaces
@@ -389,6 +384,38 @@ Issue numbers reference `python-openxml/python-docx`.
   cleanup loops, which left horizontal-rule and scratch-content artifacts
   in the document during failed-run recoveries.
 
+- **`Paragraph.add_citation(source, *, anchor=None, excerpt=None,
+  display_value=None) -> str`** + **`Paragraph.clear_citations()`** +
+  **`Document.add_citation(source, *, destination_anchor, anchor=None,
+  ...)`** + **`Document.remove_citation(citation_id)`** (0.20.0+) —
+  SDK-native Athena citations. This is the programmatic equivalent of
+  the user selecting DOCX text and choosing "Use selection as citation
+  destination/source" in Olympus: it writes the canonical document
+  citation record into the document's ``citations`` Y.Array and applies
+  the citation-blue highlight to the destination paragraph/range. It is
+  not a live link and does not overwrite destination text.
+
+  Common agent pattern after writing a supported claim:
+
+  ```python
+  from docx import Document
+  from docx._references import AssetReference, SheetRangeAnchor
+
+  doc = Document("asset_word")
+  p = doc.add_paragraph("The combined assessment identified 20,049 total vulnerabilities.")
+  citation_id = p.add_citation(
+      AssetReference(id="asset_spreadsheet"),
+      anchor=SheetRangeAnchor(sheet_id=0, range="B2:B8"),
+      excerpt="20,049 total vulnerabilities",
+      display_value="Vulnerability total",
+  )
+  doc.save()
+  ```
+
+  Use ``Document.add_citation(..., destination_anchor=PmNodeAnchor(...))``
+  only when you already have a DOCX editor anchor id. For normal writing,
+  cite the ``Paragraph`` proxy you just created or found.
+
 - **`Document.export_docx(path=None, *, include_revisions=False)
   -> bytes`** (0.11.4+) — export the document's current state as
   ``.docx`` bytes, optionally writing to ``path``. Closes the gap
@@ -397,16 +424,13 @@ Issue numbers reference `python-openxml/python-docx`.
   harnesses and CI workflows need a programmatic .docx export to
   diff against ``python-docx`` output that doesn't require a
   human-driven Olympus UI action. Routes through ``ExportDocx`` →
-  apps/api → SuperDoc's official ``doc.save({out: <tmp>})`` (the
-  recommended backend export path per the SuperDoc team — Document
-  API, not the browser-side ``editor.exportDocx`` shim). apps/api
+  apps/api's backend export path. apps/api
   writes the session state to a temp ``.docx``, reads bytes back,
   base64-encodes for the wire, and unlinks the temp in a
   ``finally`` block. The SDK decodes and writes to ``path``.
   ``include_revisions=True`` raises ``DocxError`` pre-flight:
-  ``@superdoc-dev/sdk@1.8.1``'s ``DocSaveParams`` has no
-  ``includeRevisions`` field, so honoring the flag isn't possible
-  through ``doc.save({out})``.
+  the current backend export path has no ``includeRevisions`` support,
+  so honoring the flag isn't possible yet.
 
   Template seeding: ``Document.create()`` (no ``docx=``) already
   produces an exportable asset because ``POST /docs/empty`` seeds

{athena_python_docx-0.20.0 → athena_python_docx-0.21.0}/DOCX_EXEC_LAB.md

@@ -1,7 +1,7 @@
 # DocX Execution Lab
 
 `scripts/docx_exec_lab.py` is a headless runner for quickly testing
-`athena-python-docx` snippets against Athena SuperDocument assets. It
+`athena-python-docx` snippets against Athena Word document assets. It
 shortens the debug loop by running local SDK code directly against a
 chosen DOCX Studio API, capturing stdout/stderr/errors/timings, and
 optionally exporting the result to `.docx` for assertions.
@@ -85,10 +85,10 @@ uv run python scripts/docx_exec_lab.py \
   --export-docx
 ```
 
-## Local UI With SuperDoc Embed
+## Local UI With DOCX Editor Embed
 
 The lab also includes a local-only HTML UI that wraps the same headless
-runner and iframes Olympus's existing SuperDoc embed route.
+runner and iframes Olympus's existing DOCX editor embed route.
 
 ```bash
 cd docx-studio/python-sdk
@@ -107,7 +107,7 @@ Defaults:
 The UI accepts an `asset_id`, Python code, and optional assertions. The
 right pane can mint an editable embed token through staging Agora and
 iframe the returned `https://staging-app.athenaintel.com/embed/{token}`
-URL, so changes render in the real Olympus/SuperDoc viewer.
+URL, so changes render in the real Olympus DOCX editor viewer.
 
 If the staging Agora URL differs, pass:
 

{athena_python_docx-0.20.0 → athena_python_docx-0.21.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.20.0
-Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
+Version: 0.21.0
+Summary: Drop-in replacement for python-docx that connects to Athena's DOCX Studio collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>
 License-Expression: MIT
@@ -11,6 +11,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
+Requires-Dist: athena-references>=0.1.0
 Requires-Dist: requests>=2.28
 Requires-Dist: urllib3>=1.26.6
 Provides-Extra: dev
@@ -27,7 +28,7 @@ Description-Content-Type: text/markdown
 
 # athena-python-docx
 
-Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Superdoc + Keryx collaborative document stack.
+Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Keryx-backed Word document stack.
 
 ## Quick start
 
@@ -35,7 +36,7 @@ Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that
 from docx import Document
 from docx.shared import Inches, Pt, RGBColor
 
-# Open an existing SuperDoc asset by its Athena asset_id
+# Open an existing Word document asset by its Athena asset_id
 with Document("asset_abc123") as doc:
     doc.add_heading("Market Analysis", level=1)
 
@@ -74,15 +75,14 @@ headless runner in `scripts/docx_exec_lab.py`. It executes an arbitrary
 Python snippet with this checkout of `athena-python-docx`, captures
 stdout/stderr/errors/timings, and can export the resulting `.docx` for
 text assertions. `scripts/docx_exec_lab_server.py` adds a local UI with
-an Olympus/SuperDoc embed preview pane. See `DOCX_EXEC_LAB.md`.
+an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.
 
 ## Environment variables
 
-Required when connecting to Keryx (set by Athena backend when executing in Daytona):
+Required when connecting to DOCX Studio (set by Athena backend when executing in Daytona):
 
-- `SUPERDOC_COLLAB_TOKEN` — short-lived Keryx JWT
-- `KERYX_WS_URL` — Keryx WebSocket base URL
-- `ATHENA_WORKSPACE_ID` — workspace routing segment
+- `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
+- `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token
 
 ## License
 

{athena_python_docx-0.20.0 → athena_python_docx-0.21.0}/README.md

@@ -1,6 +1,6 @@
 # athena-python-docx
 
-Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Superdoc + Keryx collaborative document stack.
+Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Keryx-backed Word document stack.
 
 ## Quick start
 
@@ -8,7 +8,7 @@ Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that
 from docx import Document
 from docx.shared import Inches, Pt, RGBColor
 
-# Open an existing SuperDoc asset by its Athena asset_id
+# Open an existing Word document asset by its Athena asset_id
 with Document("asset_abc123") as doc:
     doc.add_heading("Market Analysis", level=1)
 
@@ -47,15 +47,14 @@ headless runner in `scripts/docx_exec_lab.py`. It executes an arbitrary
 Python snippet with this checkout of `athena-python-docx`, captures
 stdout/stderr/errors/timings, and can export the resulting `.docx` for
 text assertions. `scripts/docx_exec_lab_server.py` adds a local UI with
-an Olympus/SuperDoc embed preview pane. See `DOCX_EXEC_LAB.md`.
+an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.
 
 ## Environment variables
 
-Required when connecting to Keryx (set by Athena backend when executing in Daytona):
+Required when connecting to DOCX Studio (set by Athena backend when executing in Daytona):
 
-- `SUPERDOC_COLLAB_TOKEN` — short-lived Keryx JWT
-- `KERYX_WS_URL` — Keryx WebSocket base URL
-- `ATHENA_WORKSPACE_ID` — workspace routing segment
+- `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
+- `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token
 
 ## License
 

{athena_python_docx-0.20.0 → athena_python_docx-0.21.0}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.20.0"
+__version__ = "0.21.0"
 
 from docx.api import Document
 from docx._buffer import flush_all

athena_python_docx-0.21.0/docx/_citations.py

@@ -0,0 +1,74 @@
+"""Helpers for SDK-native Athena citations."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from docx._references import AssetReference
+from docx.commands import AddCitation
+
+
+def new_citation_id() -> str:
+    return f"citation_{uuid.uuid4().hex[:12]}"
+
+
+def source_ref_to_dict(source: AssetReference) -> dict[str, Any]:
+    if not isinstance(source, AssetReference):
+        raise TypeError(f"source must be an AssetReference; got {type(source).__name__}")
+    return source.to_dict()
+
+
+def anchor_to_dict(anchor: object | None) -> dict[str, Any] | None:
+    if anchor is None:
+        return None
+    if not hasattr(anchor, "to_dict"):
+        raise TypeError(
+            "anchor must be an Anchor dataclass (SheetRangeAnchor, "
+            f"PmNodeAnchor, etc.) — got {type(anchor).__name__}"
+        )
+    value = anchor.to_dict()
+    if not isinstance(value, dict) or not value.get("type"):
+        raise TypeError("anchor.to_dict() must return a dict with a 'type' field")
+    return value
+
+
+def destination_anchor_to_dict(destination_anchor: object) -> dict[str, Any]:
+    if hasattr(destination_anchor, "to_dict"):
+        destination_anchor = destination_anchor.to_dict()
+    if not isinstance(destination_anchor, dict):
+        raise TypeError(
+            "destination_anchor must be a PmNodeAnchor, PmNodeRangeAnchor, or wire dict"
+        )
+    anchor_type = destination_anchor.get("type")
+    if anchor_type == "pm_node" and destination_anchor.get("nodeId"):
+        return dict(destination_anchor)
+    if (
+        anchor_type == "pm_node_range"
+        and destination_anchor.get("startNodeId")
+        and destination_anchor.get("endNodeId")
+    ):
+        return dict(destination_anchor)
+    raise ValueError(
+        "destination_anchor must be {'type':'pm_node','nodeId':...} or "
+        "{'type':'pm_node_range','startNodeId':...,'endNodeId':...}"
+    )
+
+
+def build_add_citation_command(
+    *,
+    destination_anchor: object,
+    source: AssetReference,
+    anchor: object | None,
+    excerpt: str | None,
+    display_value: str | None,
+) -> tuple[str, AddCitation]:
+    citation_id = new_citation_id()
+    return citation_id, AddCitation(
+        destination_anchor=destination_anchor_to_dict(destination_anchor),
+        source_ref=source_ref_to_dict(source),
+        source_anchor=anchor_to_dict(anchor),
+        citation_id=citation_id,
+        excerpt=excerpt,
+        display_value=display_value,
+    )

{athena_python_docx-0.20.0 → athena_python_docx-0.21.0}/docx/_http.py

@@ -1,10 +1,8 @@
 """HTTP bootstrap for Document.create().
 
-The SDK's primary transport is y-websocket via Superdoc; this module is
-the *only* HTTP client in the package. It exists solely so that
-``Document.create()`` can hit ``POST /docs/empty`` on docx-studio to
-provision a new SuperDocument asset and receive a collab bundle to open
-the document with.
+The SDK's transport is HTTP via docx-studio. This module keeps the
+bootstrap and upload calls on urllib so ``Document.create()`` can provision
+Word document assets without pulling in extra runtime dependencies.
 
 We use ``urllib`` from stdlib to avoid pulling ``httpx`` / ``requests``
 into the runtime — this code runs in Daytona sandboxes where every MB
@@ -15,6 +13,7 @@ from __future__ import annotations
 
 import json
 import os
+import urllib.parse
 import urllib.error
 import urllib.request
 from typing import TypedDict
@@ -26,26 +25,12 @@ from docx.errors import (
 )
 
 
-class _CollabBundle(TypedDict):
-    """The collab credentials returned alongside a freshly-created asset.
-
-    Note: env-var-shape (matches what ``Session`` reads), even though
-    the wire format from docx-studio uses different key names. The
-    keys are renamed at parse time.
-    """
-
-    SUPERDOC_COLLAB_TOKEN: str
-    KERYX_WS_URL: str
-    ATHENA_WORKSPACE_ID: str
-
-
 class CreateAssetResult(TypedDict):
     """Parsed response from ``POST /docs/empty``."""
 
     asset_id: str
     name: str
     workspace_id: str
-    collab: _CollabBundle
 
 
 _BASE_URL_ENV = "ATHENA_DOCX_BASE_URL"
@@ -67,6 +52,37 @@ def _derive_agora_base_url(docx_base_url: str) -> str | None:
     return docx_base_url.replace("docx-studio", "agora")
 
 
+def _delete_created_asset_best_effort(
+    *,
+    agora_base_url: str,
+    asset_id: str,
+    api_key: str,
+    timeout: float,
+) -> None:
+    """Best-effort rollback for create-then-import failures."""
+    from docx import __version__
+
+    delete_url = (
+        agora_base_url.rstrip().rstrip("/")
+        + "/api/docx-studio/assets/"
+        + urllib.parse.quote(asset_id, safe="")
+    )
+    req = urllib.request.Request(  # noqa: S310
+        delete_url,
+        method="DELETE",
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"athena-python-docx/{__version__}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            resp.read()
+    except Exception:  # noqa: BLE001
+        pass
+
+
 def create_empty_document(
     *,
     base_url: str | None = None,
@@ -91,8 +107,7 @@ def create_empty_document(
         timeout: Request timeout in seconds.
 
     Returns:
-        Parsed response dict with the new asset_id and a collab bundle
-        ready to feed into ``Session(..., bundle=...)``.
+        Parsed response dict with the new asset_id, display name, and workspace.
 
     Raises:
         SessionError: missing base_url or unparseable response.
@@ -182,42 +197,22 @@ def create_empty_document(
     asset_id_obj = parsed.get("assetId")
     name_obj = parsed.get("name")
     ws_obj = parsed.get("workspaceId")
-    collab_obj = parsed.get("collab")
     if not (
-        isinstance(asset_id_obj, str)
-        and isinstance(name_obj, str)
-        and isinstance(ws_obj, str)
-        and isinstance(collab_obj, dict)
+        isinstance(asset_id_obj, str) and isinstance(name_obj, str) and isinstance(ws_obj, str)
     ):
         raise SessionError(
             f"docx-studio response is missing required fields: {parsed!r}",
         )
-    token_obj = collab_obj.get("token")
-    ws_url_obj = collab_obj.get("wsUrl")
-    bundle_ws_obj = collab_obj.get("workspaceId")
-    if not (
-        isinstance(token_obj, str)
-        and isinstance(ws_url_obj, str)
-        and isinstance(bundle_ws_obj, str)
-    ):
-        raise SessionError(
-            f"docx-studio collab bundle is malformed: {collab_obj!r}",
-        )
 
     return CreateAssetResult(
         asset_id=asset_id_obj,
         name=name_obj,
         workspace_id=ws_obj,
-        collab=_CollabBundle(
-            SUPERDOC_COLLAB_TOKEN=token_obj,
-            KERYX_WS_URL=ws_url_obj,
-            ATHENA_WORKSPACE_ID=bundle_ws_obj,
-        ),
     )
 
 
 class UploadAssetResult(TypedDict):
-    """Parsed response from agora's ``POST /api/super-docs/create-from-upload``."""
+    """Parsed response from the create-and-import upload flow."""
 
     asset_id: str
     name: str
@@ -231,14 +226,13 @@ def upload_document(
     api_key: str | None = None,
     name: str | None = None,
     parent_folder_id: str | None = None,
+    workspace_id: str | None = None,
     timeout: float = 120.0,
 ) -> UploadAssetResult:
-    """Upload a local ``.docx`` to agora and create a new SuperDocument asset.
+    """Upload a local ``.docx`` to agora and create a new Word document asset.
 
-    The endpoint lives on agora (``POST /api/super-docs/create-from-upload``),
-    not docx-studio, because the upload + Y.Doc-seed path is implemented
-    server-side in agora. The SDK still talks to docx-studio for command
-    application; this function only handles the initial create.
+    The upload path creates a normal Word document asset through agora's
+    docx-studio bridge, then imports the local ``.docx`` into that asset.
 
     Args:
         docx_path: Filesystem path to the ``.docx`` to upload.
@@ -251,6 +245,8 @@ def upload_document(
         api_key: Athena API key. Falls back to ``$ATHENA_DOCX_API_KEY``.
         name: Optional asset title (defaults to the file's stem).
         parent_folder_id: Optional parent folder for the new asset.
+        workspace_id: Optional workspace UUID; defaults to the caller's
+            current workspace as resolved by Agora.
         timeout: Request timeout in seconds (uploads can be slow for big
             decks/templates).
 
@@ -262,10 +258,8 @@ def upload_document(
         AuthenticationError: missing api_key, or 401/403 from server.
         DocxError: any other 4xx/5xx, or a malformed response.
     """
-    import io
-    import mimetypes
+    import base64
     import os
-    import uuid
 
     resolved_docx_base: str | None = docx_base_url or os.environ.get(_BASE_URL_ENV)
     # Create must authenticate as the REAL user so the new asset's ``created_by``
@@ -311,49 +305,25 @@ def upload_document(
         base = os.path.basename(docx_path)
         title = base[:-5] if base.lower().endswith(".docx") else base
 
-    # Build the agora URL with query-string params (FastAPI binds non-body
-    # args from the query string for multipart routes).
-    from urllib.parse import urlencode
+    with open(docx_path, "rb") as f:
+        file_bytes: bytes = f.read()
 
-    qs: dict[str, str] = {"is_template": "false", "title": title}
+    create_body: dict[str, str] = {"name": title}
     if parent_folder_id is not None:
-        qs["parent_folder_id"] = parent_folder_id
-
-    url: str = (
-        resolved_agora_base.rstrip("/") + "/api/super-docs/create-from-upload?" + urlencode(qs)
-    )
+        create_body["parent_folder_id"] = parent_folder_id
+    if workspace_id is not None:
+        create_body["workspace_id"] = workspace_id
 
-    # Build a minimal multipart/form-data body without pulling in
-    # `requests` — keep the urllib-only dep profile.
-    with open(docx_path, "rb") as f:
-        file_bytes: bytes = f.read()
-    content_type: str = (
-        mimetypes.guess_type(docx_path)[0]
-        or "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
-    )
-    boundary: str = f"----athenaDocxBoundary{uuid.uuid4().hex}"
-    filename = os.path.basename(docx_path)
-    body_parts: list[bytes] = []
-    body_parts.append(f"--{boundary}\r\n".encode("utf-8"))
-    body_parts.append(
-        (
-            'Content-Disposition: form-data; name="file"; '
-            f'filename="{filename}"\r\n'
-            f"Content-Type: {content_type}\r\n\r\n"
-        ).encode("utf-8"),
-    )
-    body_parts.append(file_bytes)
-    body_parts.append(f"\r\n--{boundary}--\r\n".encode("utf-8"))
-    body: bytes = b"".join(body_parts)
+    create_url: str = resolved_agora_base.rstrip("/") + "/api/docx-studio/assets"
 
     from docx import __version__
 
     req = urllib.request.Request(  # noqa: S310
-        url,
-        data=body,
+        create_url,
+        data=json.dumps(create_body).encode("utf-8"),
         method="POST",
         headers={
-            "Content-Type": f"multipart/form-data; boundary={boundary}",
+            "Content-Type": "application/json",
             "Authorization": f"Bearer {resolved_key}",
             "Accept": "application/json",
             "User-Agent": f"athena-python-docx/{__version__}",
@@ -374,15 +344,13 @@ def upload_document(
                 f"agora rejected the API key (HTTP {e.code}): {err_body}",
             ) from e
         raise DocxError(
-            f"agora /api/super-docs/create-from-upload returned HTTP {e.code}: {err_body}",
+            f"agora /api/docx-studio/assets returned HTTP {e.code}: {err_body}",
         ) from e
     except urllib.error.URLError as e:
         raise SessionError(
-            f"Unable to reach agora at {url}: {e.reason}",
+            f"Unable to reach agora at {create_url}: {e.reason}",
         ) from e
 
-    # Avoid unused import warning when io isn't otherwise referenced.
-    _ = io
     try:
         parsed: dict = json.loads(raw.decode("utf-8"))
     except (UnicodeDecodeError, json.JSONDecodeError) as e:
@@ -390,11 +358,74 @@ def upload_document(
             f"agora returned non-JSON response: {raw[:200]!r}",
         ) from e
 
-    asset_id_obj = parsed.get("id")
-    name_obj = parsed.get("title")
+    asset_id_obj = parsed.get("asset_id")
+    name_obj = parsed.get("name")
     if not (isinstance(asset_id_obj, str) and isinstance(name_obj, str)):
         raise SessionError(
             f"agora response is missing required fields: {parsed!r}",
         )
 
+    import_url: str = (
+        resolved_agora_base.rstrip("/")
+        + "/api/docx-studio/assets/"
+        + urllib.parse.quote(asset_id_obj, safe="")
+        + "/import"
+    )
+    import_body = {
+        "docx_base64": base64.b64encode(file_bytes).decode("ascii"),
+        "overwrite": True,
+    }
+    import_req = urllib.request.Request(  # noqa: S310
+        import_url,
+        data=json.dumps(import_body).encode("utf-8"),
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {resolved_key}",
+            "Accept": "application/json",
+            "User-Agent": f"athena-python-docx/{__version__}",
+        },
+    )
+
+    try:
+        try:
+            with urllib.request.urlopen(import_req, timeout=timeout) as resp:  # noqa: S310
+                import_raw: bytes = resp.read()
+        except urllib.error.HTTPError as e:
+            err_body = ""
+            try:
+                err_body = e.read().decode("utf-8", errors="replace")
+            except Exception:  # noqa: BLE001
+                pass
+            if e.code in (401, 403):
+                raise AuthenticationError(
+                    f"agora rejected the API key while importing DOCX (HTTP {e.code}): {err_body}",
+                ) from e
+            raise DocxError(
+                f"agora /api/docx-studio/assets/{asset_id_obj}/import returned HTTP {e.code}: {err_body}",
+            ) from e
+        except urllib.error.URLError as e:
+            raise SessionError(
+                f"Unable to reach agora at {import_url}: {e.reason}",
+            ) from e
+
+        try:
+            import_parsed: dict = json.loads(import_raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as e:
+            raise SessionError(
+                f"agora import returned non-JSON response: {import_raw[:200]!r}",
+            ) from e
+        if import_parsed.get("asset_id") != asset_id_obj or import_parsed.get("seeded") is not True:
+            raise SessionError(
+                f"agora import response is missing required fields: {import_parsed!r}",
+            )
+    except Exception:
+        _delete_created_asset_best_effort(
+            agora_base_url=resolved_agora_base,
+            asset_id=asset_id_obj,
+            api_key=resolved_key,
+            timeout=timeout,
+        )
+        raise
+
     return UploadAssetResult(asset_id=asset_id_obj, name=name_obj)