> ISPO SDK documentation. [HTML](https://ispo.ai/docs/interfaces/core.FilesApi.html) · [Documentation index](https://ispo.ai/docs/llms.txt)

# Interface FilesApi

```typescript
interface FilesApi {
    editSession: FilesEditSessionApi;
    list(): Promise<FilesListEntry[]>;
    openWith(args: FilesOpenWithArgs): Promise<FilesOpenWithResult>;
    pick(
        args?: PowerboxOpenArgs,
    ): Promise<PowerboxPickResult | PowerboxPickResult[] | null>;
    publish(args: FilesPublishArgs): Promise<FilesPublishResult>;
    save(args: PowerboxSaveArgs): Promise<PowerboxSaveResult | null>;
}
```

Types: [editSession](#editsession), [FilesEditSessionApi](core.FilesEditSessionApi.md), [list](#list-1), [FilesListEntry](core.Supporting_types.FilesListEntry.md), [openWith](#openwith-1), [FilesOpenWithArgs](core.FilesOpenWithArgs.md), [FilesOpenWithResult](core.FilesOpenWithResult.md), [pick](#pick-1), [PowerboxOpenArgs](core.PowerboxOpenArgs.md), [PowerboxPickResult](core.PowerboxPickResult.md), [publish](#publish-1), [FilesPublishArgs](../types/core.FilesPublishArgs.md), [FilesPublishResult](core.FilesPublishResult.md), [save](#save-1), [PowerboxSaveArgs](core.PowerboxSaveArgs.md), [PowerboxSaveResult](core.PowerboxSaveResult.md)

##### Index

### <a id="properties"></a>Properties

[editSession](#editsession)

### <a id="methods"></a>Methods

[list](#list) [openWith](#openwith) [pick](#pick) [publish](#publish) [save](#save)

## <a id="properties-1"></a>Properties

### <a id="editsession"></a>editSession

```typescript
editSession: FilesEditSessionApi
```

Types: [FilesEditSessionApi](core.FilesEditSessionApi.md)

## <a id="methods-1"></a>Methods

### <a id="list"></a>list

*   <a id="list-1"></a>
    
    ```typescript
    list(): Promise<FilesListEntry[]>
    ```
    
    Types: [FilesListEntry](core.Supporting_types.FilesListEntry.md)
    
    List this project's OWN published Files entries (spec §19.3). Non- interactive read of the caller's own owner-stamped artifacts — no picker, no gesture, and never another project's Files. Rides the same `files.publish` two-gate as [publish](#publish).
    
    #### Returns Promise<[FilesListEntry](core.Supporting_types.FilesListEntry.md)\[\]\>
    

**Authority for `files.list`**

Reviewed request token: `files.publish`. Standing capability: `files.publish`.

Handle structured `ProjectRpcError` failures. A timeout does not guarantee cancellation; do not automatically retry effects without a documented idempotency contract. [Method authority and recovery](/docs/documents/Method_authority.md). [Example, effects, and verification](/docs/documents/Publish_a_file.md).

### <a id="openwith"></a>openWith

*   <a id="openwith-1"></a>
    
    ```typescript
    openWith(args: FilesOpenWithArgs): Promise<FilesOpenWithResult>
    ```
    
    Types: [FilesOpenWithArgs](core.FilesOpenWithArgs.md), [FilesOpenWithResult](core.FilesOpenWithResult.md)
    
    #### Parameters
    
    *   args: [FilesOpenWithArgs](core.FilesOpenWithArgs.md)
    
    #### Returns Promise<[FilesOpenWithResult](core.FilesOpenWithResult.md)\>
    

**Authority for `files.openWith`**

Reviewed request token: `files.edit`. No static standing capability. Resource bindings, identity checks, or interactive consent may still apply.

Handle structured `ProjectRpcError` failures. A timeout does not guarantee cancellation; do not automatically retry effects without a documented idempotency contract. [Method authority and recovery](/docs/documents/Method_authority.md). [Example, effects, and verification](/docs/documents/Publish_a_file.md).

### <a id="pick"></a>pick

*   <a id="pick-1"></a>
    
    ```typescript
    pick(
        args?: PowerboxOpenArgs,
    ): Promise<PowerboxPickResult | PowerboxPickResult[] | null>
    ```
    
    Types: [PowerboxOpenArgs](core.PowerboxOpenArgs.md), [PowerboxPickResult](core.PowerboxPickResult.md)
    
    Powerbox Open: browse Files entries and receive the user's pick(s) by pure copy / controlled reference. Single-select returns a bare result; pass `multiple: true` to receive an array. `null` on cancel.
    
    #### Parameters
    
    *   `Optional`args: [PowerboxOpenArgs](core.PowerboxOpenArgs.md)
    
    #### Returns Promise<[PowerboxPickResult](core.PowerboxPickResult.md) | [PowerboxPickResult](core.PowerboxPickResult.md)\[\] | null\>
    

**Authority for `files.pick`**

Reviewed request token: `files.pick`. No static standing capability. Resource bindings, identity checks, or interactive consent may still apply.

Handle structured `ProjectRpcError` failures. A timeout does not guarantee cancellation; do not automatically retry effects without a documented idempotency contract. [Method authority and recovery](/docs/documents/Method_authority.md). [Example, effects, and verification](/docs/documents/Publish_a_file.md).

### <a id="publish"></a>publish

*   <a id="publish-1"></a>
    
    ```typescript
    publish(args: FilesPublishArgs): Promise<FilesPublishResult>
    ```
    
    Types: [FilesPublishArgs](../types/core.FilesPublishArgs.md), [FilesPublishResult](core.FilesPublishResult.md)
    
    #### Parameters
    
    *   args: [FilesPublishArgs](../types/core.FilesPublishArgs.md)
    
    #### Returns Promise<[FilesPublishResult](core.FilesPublishResult.md)\>
    

**Authority for `files.publish`**

Reviewed request token: `files.publish`. Standing capability: `files.publish`.

Handle structured `ProjectRpcError` failures. A timeout does not guarantee cancellation; do not automatically retry effects without a documented idempotency contract. [Method authority and recovery](/docs/documents/Method_authority.md). [Example, effects, and verification](/docs/documents/Publish_a_file.md).

### <a id="save"></a>save

*   <a id="save-1"></a>
    
    ```typescript
    save(args: PowerboxSaveArgs): Promise<PowerboxSaveResult | null>
    ```
    
    Types: [PowerboxSaveArgs](core.PowerboxSaveArgs.md), [PowerboxSaveResult](core.PowerboxSaveResult.md)
    
    Powerbox Save: hand the host bytes and let the user publish them to Files. `null` on cancel.
    
    #### Parameters
    
    *   args: [PowerboxSaveArgs](core.PowerboxSaveArgs.md)
    
    #### Returns Promise<[PowerboxSaveResult](core.PowerboxSaveResult.md) | null\>
    

**Authority for `files.save`**

Reviewed request token: `files.pick`. No static standing capability. Resource bindings, identity checks, or interactive consent may still apply.

Handle structured `ProjectRpcError` failures. A timeout does not guarantee cancellation; do not automatically retry effects without a documented idempotency contract. [Method authority and recovery](/docs/documents/Method_authority.md). [Example, effects, and verification](/docs/documents/Publish_a_file.md).