archastro.platform.v1.resources.agent_installations

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 318185ae3f1e
  4
  5from __future__ import annotations
  6
  7import builtins
  8from typing import Any, TypedDict
  9
 10from ...runtime.http_client import HttpClient, SyncHttpClient
 11from ...types.common import (
 12    Installation,
 13    InstallationListResponse,
 14    InstallationSource,
 15    InstallationSourceListResponse,
 16)
 17
 18
 19class AgentInstallationInstallationSourceCreateInput(TypedDict):
 20    "Add a source to an installation"
 21
 22    payload: dict[str, Any]
 23    "Type-specific payload for the source. The accepted keys depend on the `type` value; invalid or missing payload fields return 422."
 24    type: str
 25    'Source type slug identifying the kind of content being attached, e.g. `"file/document"` or `"web/link"`.'
 26
 27
 28class AgentInstallationSuspendInput(TypedDict, total=False):
 29    "Suspend an installation"
 30
 31    reason: str | None
 32    "Human-readable explanation for the suspension. Stored on the installation and visible when you retrieve it. Omit to suspend without recording a reason."
 33
 34
 35class AsyncAgentInstallationInstallationSourceResource:
 36    def __init__(self, http: HttpClient):
 37        self._http = http
 38
 39    async def list(self, installation: str) -> InstallationSourceListResponse:
 40        """
 41        List sources for an installation
 42        Returns all sources attached to the specified installation. Sources represent
 43        the content units (documents, links, and other typed payloads) that the
 44        installation's agent can access as context.
 45        This endpoint requires an app-scoped token. Results include sources in all
 46        states, including those still being ingested. Inspect each source's `state`
 47        field to determine whether its content is ready.
 48
 49        Args:
 50            installation: Installation ID (`cin_...`) whose sources to retrieve.
 51
 52        Returns:
 53            Object containing the list of sources attached to the installation.
 54        """
 55        return await self._http.request(
 56            f"/api/v1/agent_installations/{installation}/installation_sources",
 57            response_type=InstallationSourceListResponse,
 58        )
 59
 60    async def create(
 61        self, installation: str, input: AgentInstallationInstallationSourceCreateInput
 62    ) -> InstallationSource:
 63        """
 64        Add a source to an installation
 65        Attaches a new source to an existing installation, making its content available
 66        to the installation's agent as context. The source type and payload must be valid
 67        for the installation's kind; invalid combinations return 422.
 68        This endpoint requires an app-scoped token. The installation must belong to an
 69        agent accessible by the authenticated caller. Once created, the source begins
 70        processing asynchronously its `state` will transition from `"pending"` as
 71        ingestion progresses.
 72
 73        Args:
 74            installation: Installation ID (`cin_...`) whose sources to retrieve.
 75            input: Request body.
 76            input.payload: Type-specific payload for the source. The accepted keys depend on the `type` value; invalid or missing payload fields return 422.
 77            input.type: Source type slug identifying the kind of content being attached, e.g. `"file/document"` or `"web/link"`.
 78
 79        Returns:
 80            The newly created installation source.
 81        """
 82        return await self._http.request(
 83            f"/api/v1/agent_installations/{installation}/installation_sources",
 84            method="POST",
 85            body=input,
 86            response_type=InstallationSource,
 87        )
 88
 89
 90class AsyncAgentInstallationResource:
 91    def __init__(self, http: HttpClient):
 92        self._http = http
 93        self.installation_sources = AsyncAgentInstallationInstallationSourceResource(http)
 94
 95    async def list(self, *, agent: builtins.list[str] | None = None) -> InstallationListResponse:
 96        """
 97        List installations for an app
 98        Returns all installations across every agent in the authenticated app. Use this
 99        endpoint to get a global view of all external service and enablement channel
100        connections for the app.
101        Optionally narrow results to a single agent by passing the `agent` parameter. To
102        list installations scoped to a specific agent, you may also use the per-agent List
103        Installations endpoint. Results are returned as an unordered array with no
104        pagination. The caller must have app scope.
105
106        Args:
107            agent: Agent IDs (`agi_...`) to filter results by. When omitted, installations for all agents in the app are returned. Multiple values are OR'd.
108
109        Returns:
110            The list of installations for the app, optionally filtered by agent.
111        """
112        query: dict[str, object] = {}
113        if agent is not None:
114            query["agent"] = agent
115        return await self._http.request(
116            "/api/v1/agent_installations",
117            query=query,
118            response_type=InstallationListResponse,
119        )
120
121    async def delete(self, installation: str) -> None:
122        """
123        Delete an installation
124        Permanently deletes an installation and severs the connection between the agent
125        and the external service or enablement channel. Any backing context sources
126        associated with the installation are also removed.
127        This action is irreversible. If you want to temporarily stop an installation from
128        processing events, use the Pause or Suspend endpoints instead. The caller must have
129        app scope for the app that owns the installation.
130
131        Args:
132            installation: Installation ID (`cin_...`) to delete.
133
134        Returns:
135            Empty response with HTTP 204 status on successful deletion.
136        """
137        await self._http.request(f"/api/v1/agent_installations/{installation}", method="DELETE")
138
139    async def get(self, installation: str) -> Installation:
140        """
141        Retrieve an installation
142        Returns a single installation by ID. Use this endpoint to check the current
143        `state`, `kind`, `config`, and bound integration of an installation.
144        The installation must belong to an agent that is accessible within the
145        authenticated app's scope. The caller must have app scope for the app that
146        owns the installation.
147
148        Args:
149            installation: Installation ID (`cin_...`) to retrieve.
150
151        Returns:
152            The requested installation.
153        """
154        return await self._http.request(
155            f"/api/v1/agent_installations/{installation}",
156            response_type=Installation,
157        )
158
159    async def activate(self, installation: str) -> Installation:
160        """
161        Activate an installation
162        Transitions an installation from a pending or paused state to `active`, enabling
163        the agent to receive events and process work through the installed integration or
164        enablement channel.
165        Activation requires that the installation already has a bound integration (either
166        via `shared_integration` or an inline `integration` created at install time). If no
167        integration is bound, the request returns 422. The caller must have app scope for
168        the app that owns the installation.
169
170        Args:
171            installation: Installation ID (`cin_...`) to activate.
172
173        Returns:
174            The updated installation with `state` reflecting the new active status.
175        """
176        return await self._http.request(
177            f"/api/v1/agent_installations/{installation}/activate",
178            method="POST",
179            response_type=Installation,
180        )
181
182    async def pause(self, installation: str) -> Installation:
183        """
184        Pause an installation
185        Transitions an active installation to the `paused` state, temporarily stopping
186        the agent from receiving events through this installation. The installation and
187        its integration binding are preserved and can be resumed by calling the Activate
188        endpoint.
189        Only installations in the `active` state can be paused. Attempting to pause an
190        installation in any other state returns 422. The caller must have app scope for
191        the app that owns the installation.
192
193        Args:
194            installation: Installation ID (`cin_...`) to pause.
195
196        Returns:
197            The updated installation with `state` set to `"paused"`.
198        """
199        return await self._http.request(
200            f"/api/v1/agent_installations/{installation}/pause",
201            method="POST",
202            response_type=Installation,
203        )
204
205    async def suspend(
206        self, installation: str, input: AgentInstallationSuspendInput
207    ) -> Installation:
208        """
209        Suspend an installation
210        Transitions an installation to the `suspended` state, disabling event processing
211        and signaling that the installation requires administrative attention. Unlike
212        pausing, suspension typically indicates a policy or compliance hold rather than a
213        temporary operational stop.
214        An optional `reason` string can be supplied to record why the installation was
215        suspended; this is stored on the installation and visible when you retrieve it.
216        Only installations that are not already suspended can be suspended sending this
217        request for an already-suspended installation returns 422. The caller must have
218        app scope for the app that owns the installation.
219
220        Args:
221            installation: Installation ID (`cin_...`) to suspend.
222            input: Request body.
223            input.reason: Human-readable explanation for the suspension. Stored on the installation and visible when you retrieve it. Omit to suspend without recording a reason.
224
225        Returns:
226            The updated installation with `state` set to `"suspended"`.
227        """
228        return await self._http.request(
229            f"/api/v1/agent_installations/{installation}/suspend",
230            method="POST",
231            body=input,
232            response_type=Installation,
233        )
234
235
236class AgentInstallationInstallationSourceResource:
237    def __init__(self, http: SyncHttpClient):
238        self._http = http
239
240    def list(self, installation: str) -> InstallationSourceListResponse:
241        """
242        List sources for an installation
243        Returns all sources attached to the specified installation. Sources represent
244        the content units (documents, links, and other typed payloads) that the
245        installation's agent can access as context.
246        This endpoint requires an app-scoped token. Results include sources in all
247        states, including those still being ingested. Inspect each source's `state`
248        field to determine whether its content is ready.
249
250        Args:
251            installation: Installation ID (`cin_...`) whose sources to retrieve.
252
253        Returns:
254            Object containing the list of sources attached to the installation.
255        """
256        return self._http.request(
257            f"/api/v1/agent_installations/{installation}/installation_sources",
258            response_type=InstallationSourceListResponse,
259        )
260
261    def create(
262        self, installation: str, input: AgentInstallationInstallationSourceCreateInput
263    ) -> InstallationSource:
264        """
265        Add a source to an installation
266        Attaches a new source to an existing installation, making its content available
267        to the installation's agent as context. The source type and payload must be valid
268        for the installation's kind; invalid combinations return 422.
269        This endpoint requires an app-scoped token. The installation must belong to an
270        agent accessible by the authenticated caller. Once created, the source begins
271        processing asynchronously its `state` will transition from `"pending"` as
272        ingestion progresses.
273
274        Args:
275            installation: Installation ID (`cin_...`) whose sources to retrieve.
276            input: Request body.
277            input.payload: Type-specific payload for the source. The accepted keys depend on the `type` value; invalid or missing payload fields return 422.
278            input.type: Source type slug identifying the kind of content being attached, e.g. `"file/document"` or `"web/link"`.
279
280        Returns:
281            The newly created installation source.
282        """
283        return self._http.request(
284            f"/api/v1/agent_installations/{installation}/installation_sources",
285            method="POST",
286            body=input,
287            response_type=InstallationSource,
288        )
289
290
291class AgentInstallationResource:
292    def __init__(self, http: SyncHttpClient):
293        self._http = http
294        self.installation_sources = AgentInstallationInstallationSourceResource(http)
295
296    def list(self, *, agent: builtins.list[str] | None = None) -> InstallationListResponse:
297        """
298        List installations for an app
299        Returns all installations across every agent in the authenticated app. Use this
300        endpoint to get a global view of all external service and enablement channel
301        connections for the app.
302        Optionally narrow results to a single agent by passing the `agent` parameter. To
303        list installations scoped to a specific agent, you may also use the per-agent List
304        Installations endpoint. Results are returned as an unordered array with no
305        pagination. The caller must have app scope.
306
307        Args:
308            agent: Agent IDs (`agi_...`) to filter results by. When omitted, installations for all agents in the app are returned. Multiple values are OR'd.
309
310        Returns:
311            The list of installations for the app, optionally filtered by agent.
312        """
313        query: dict[str, object] = {}
314        if agent is not None:
315            query["agent"] = agent
316        return self._http.request(
317            "/api/v1/agent_installations",
318            query=query,
319            response_type=InstallationListResponse,
320        )
321
322    def delete(self, installation: str) -> None:
323        """
324        Delete an installation
325        Permanently deletes an installation and severs the connection between the agent
326        and the external service or enablement channel. Any backing context sources
327        associated with the installation are also removed.
328        This action is irreversible. If you want to temporarily stop an installation from
329        processing events, use the Pause or Suspend endpoints instead. The caller must have
330        app scope for the app that owns the installation.
331
332        Args:
333            installation: Installation ID (`cin_...`) to delete.
334
335        Returns:
336            Empty response with HTTP 204 status on successful deletion.
337        """
338        self._http.request(f"/api/v1/agent_installations/{installation}", method="DELETE")
339
340    def get(self, installation: str) -> Installation:
341        """
342        Retrieve an installation
343        Returns a single installation by ID. Use this endpoint to check the current
344        `state`, `kind`, `config`, and bound integration of an installation.
345        The installation must belong to an agent that is accessible within the
346        authenticated app's scope. The caller must have app scope for the app that
347        owns the installation.
348
349        Args:
350            installation: Installation ID (`cin_...`) to retrieve.
351
352        Returns:
353            The requested installation.
354        """
355        return self._http.request(
356            f"/api/v1/agent_installations/{installation}",
357            response_type=Installation,
358        )
359
360    def activate(self, installation: str) -> Installation:
361        """
362        Activate an installation
363        Transitions an installation from a pending or paused state to `active`, enabling
364        the agent to receive events and process work through the installed integration or
365        enablement channel.
366        Activation requires that the installation already has a bound integration (either
367        via `shared_integration` or an inline `integration` created at install time). If no
368        integration is bound, the request returns 422. The caller must have app scope for
369        the app that owns the installation.
370
371        Args:
372            installation: Installation ID (`cin_...`) to activate.
373
374        Returns:
375            The updated installation with `state` reflecting the new active status.
376        """
377        return self._http.request(
378            f"/api/v1/agent_installations/{installation}/activate",
379            method="POST",
380            response_type=Installation,
381        )
382
383    def pause(self, installation: str) -> Installation:
384        """
385        Pause an installation
386        Transitions an active installation to the `paused` state, temporarily stopping
387        the agent from receiving events through this installation. The installation and
388        its integration binding are preserved and can be resumed by calling the Activate
389        endpoint.
390        Only installations in the `active` state can be paused. Attempting to pause an
391        installation in any other state returns 422. The caller must have app scope for
392        the app that owns the installation.
393
394        Args:
395            installation: Installation ID (`cin_...`) to pause.
396
397        Returns:
398            The updated installation with `state` set to `"paused"`.
399        """
400        return self._http.request(
401            f"/api/v1/agent_installations/{installation}/pause",
402            method="POST",
403            response_type=Installation,
404        )
405
406    def suspend(self, installation: str, input: AgentInstallationSuspendInput) -> Installation:
407        """
408        Suspend an installation
409        Transitions an installation to the `suspended` state, disabling event processing
410        and signaling that the installation requires administrative attention. Unlike
411        pausing, suspension typically indicates a policy or compliance hold rather than a
412        temporary operational stop.
413        An optional `reason` string can be supplied to record why the installation was
414        suspended; this is stored on the installation and visible when you retrieve it.
415        Only installations that are not already suspended can be suspended sending this
416        request for an already-suspended installation returns 422. The caller must have
417        app scope for the app that owns the installation.
418
419        Args:
420            installation: Installation ID (`cin_...`) to suspend.
421            input: Request body.
422            input.reason: Human-readable explanation for the suspension. Stored on the installation and visible when you retrieve it. Omit to suspend without recording a reason.
423
424        Returns:
425            The updated installation with `state` set to `"suspended"`.
426        """
427        return self._http.request(
428            f"/api/v1/agent_installations/{installation}/suspend",
429            method="POST",
430            body=input,
431            response_type=Installation,
432        )