archastro.platform.v1.resources.files

  1# Copyright (c) 2026 ArchAstro Inc. All Rights Reserved.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 1b30908faf43
  4
  5from __future__ import annotations
  6
  7from typing import Required, TypedDict
  8
  9from ...runtime.http_client import HttpClient, SyncHttpClient
 10from ...types.common import StorageFile
 11
 12
 13class FileCreateInput(TypedDict, total=False):
 14    "Upload a file"
 15
 16    agent: str | None
 17    "Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent."
 18    content_type: Required[str]
 19    'MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.'
 20    data: Required[str]
 21    "Base64-encoded binary content of the file to upload."
 22    filename: Required[str]
 23    'Original filename including extension, e.g. `"avatar.png"`.'
 24    org: str | None
 25    "Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted."
 26    team: str | None
 27    "Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided."
 28    user: str | None
 29    "User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified."
 30
 31
 32class AsyncFileResource:
 33    def __init__(self, http: HttpClient):
 34        self._http = http
 35
 36    async def create(self, input: FileCreateInput) -> StorageFile:
 37        """
 38        Upload a file
 39        Creates a new file from base64-encoded content and returns the resulting file object,
 40        including a signed download URL. Use this endpoint to store images, documents, or
 41        other binary assets that can then be referenced by agents, teams, or users.
 42        App scope is derived from the authenticated viewer's bearer token or publishable key.
 43        You may optionally associate the file with an organization, team, user, or agent by
 44        passing the corresponding ID. If no owner is specified and the viewer is a user, the
 45        file is automatically attributed to that user.
 46        Returns `422` when the `data` field is not valid base64 or the changeset is invalid.
 47        Returns `403` when the request lacks the required app scope.
 48
 49        Args:
 50            input: Request body.
 51            input.agent: Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent.
 52            input.content_type: MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
 53            input.data: Base64-encoded binary content of the file to upload.
 54            input.filename: Original filename including extension, e.g. `"avatar.png"`.
 55            input.org: Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted.
 56            input.team: Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided.
 57            input.user: User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified.
 58
 59        Returns:
 60            The newly created file, including a signed download URL.
 61        """
 62        return await self._http.request(
 63            "/api/v1/files",
 64            method="POST",
 65            body=input,
 66            response_type=StorageFile,
 67        )
 68
 69    async def avatar(self, file: str, token: str) -> dict[str, str]:
 70        """
 71        Fetch an agent avatar image
 72        Returns the raw image bytes for an agent's profile picture identified by `file`.
 73        This endpoint is designed for integration partners (such as Slack) that fetch
 74        avatar URLs via plain GET requests without bearer token support. Authorization
 75        is performed via a short, stable capability `token` rather than an HTTP header.
 76        The `token` is an HMAC-based capability tied to the file ID. It does not expire,
 77        but it is invalidated when the agent's profile picture is replaced or the agent is
 78        deleted shared caches may continue serving the old image until the
 79        `Cache-Control` max-age of one hour elapses. The endpoint never redirects to
 80        a signed storage URL; bytes are served inline so behavior is consistent across
 81        storage backends.
 82        All failure modes invalid file ID, invalid token, file not currently referenced
 83        as an agent avatar return a uniform `404` to avoid acting as an existence oracle.
 84
 85        Args:
 86            file: File ID of the agent's profile picture (`fil_...`). Must be currently set as an agent's profile picture within the same app.
 87            token: HMAC capability token authorizing access to this specific file. Obtained from the avatar URL minted when the profile picture was set.
 88
 89        Returns:
 90            Raw image bytes of the agent avatar, served with the file's original content type.
 91        """
 92        query: dict[str, object] = {}
 93        query["token"] = token
 94        return await self._http.request_raw(f"/api/v1/files/{file}/avatar", query=query)
 95
 96
 97class FileResource:
 98    def __init__(self, http: SyncHttpClient):
 99        self._http = http
100
101    def create(self, input: FileCreateInput) -> StorageFile:
102        """
103        Upload a file
104        Creates a new file from base64-encoded content and returns the resulting file object,
105        including a signed download URL. Use this endpoint to store images, documents, or
106        other binary assets that can then be referenced by agents, teams, or users.
107        App scope is derived from the authenticated viewer's bearer token or publishable key.
108        You may optionally associate the file with an organization, team, user, or agent by
109        passing the corresponding ID. If no owner is specified and the viewer is a user, the
110        file is automatically attributed to that user.
111        Returns `422` when the `data` field is not valid base64 or the changeset is invalid.
112        Returns `403` when the request lacks the required app scope.
113
114        Args:
115            input: Request body.
116            input.agent: Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent.
117            input.content_type: MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
118            input.data: Base64-encoded binary content of the file to upload.
119            input.filename: Original filename including extension, e.g. `"avatar.png"`.
120            input.org: Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted.
121            input.team: Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided.
122            input.user: User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified.
123
124        Returns:
125            The newly created file, including a signed download URL.
126        """
127        return self._http.request(
128            "/api/v1/files",
129            method="POST",
130            body=input,
131            response_type=StorageFile,
132        )
133
134    def avatar(self, file: str, token: str) -> dict[str, str]:
135        """
136        Fetch an agent avatar image
137        Returns the raw image bytes for an agent's profile picture identified by `file`.
138        This endpoint is designed for integration partners (such as Slack) that fetch
139        avatar URLs via plain GET requests without bearer token support. Authorization
140        is performed via a short, stable capability `token` rather than an HTTP header.
141        The `token` is an HMAC-based capability tied to the file ID. It does not expire,
142        but it is invalidated when the agent's profile picture is replaced or the agent is
143        deleted shared caches may continue serving the old image until the
144        `Cache-Control` max-age of one hour elapses. The endpoint never redirects to
145        a signed storage URL; bytes are served inline so behavior is consistent across
146        storage backends.
147        All failure modes invalid file ID, invalid token, file not currently referenced
148        as an agent avatar return a uniform `404` to avoid acting as an existence oracle.
149
150        Args:
151            file: File ID of the agent's profile picture (`fil_...`). Must be currently set as an agent's profile picture within the same app.
152            token: HMAC capability token authorizing access to this specific file. Obtained from the avatar URL minted when the profile picture was set.
153
154        Returns:
155            Raw image bytes of the agent avatar, served with the file's original content type.
156        """
157        query: dict[str, object] = {}
158        query["token"] = token
159        return self._http.request_raw(f"/api/v1/files/{file}/avatar", query=query)