Skip to content

API Reference

This section provides a detailed API reference for all public classes, methods, and functions in the frameio-kit library.

frameio_kit

Modules:

  • app –

    The central module for the Frame.io SDK application.

  • client –
  • events –

    Pydantic models for parsing incoming Frame.io webhook and action events.

  • middleware –

    Middleware system for adding cross-cutting concerns to Frame.io integrations.

  • security –
  • ui –

    Pydantic models for generating UI responses for Frame.io Custom Actions.

Classes:

  • App –

    The main application class for building Frame.io integrations.

  • Client –

    Asynchronous HTTP client for interacting with the Frame.io v4 API.

  • Account –

    Represents the account context, used in standard webhook payloads.

  • ActionEvent –

    A custom action event payload, including user-submitted form data.

  • Project –

    Represents the project context in which an event occurred.

  • Resource –

    Represents the primary resource that an event pertains to.

  • User –

    Represents the user who initiated the event.

  • WebhookEvent –

    A standard webhook event payload from Frame.io.

  • Workspace –

    Represents the workspace (formerly Team) in which an event occurred.

  • Middleware –

    Base class for creating middleware in Frame.io integrations.

  • CheckboxField –

    A checkbox input.

  • Form –

    A modal with a form to collect input from the user.

  • LinkField –

    A non-editable field that displays a URL with a "Copy" button.

  • Message –

    A simple message modal to display information to the user.

  • SelectField –

    A dropdown menu allowing the user to select one from a list of options.

  • SelectOption –

    Represents a single choice within a SelectField.

  • TextareaField –

    A multi-line text input area, suitable for longer descriptions.

  • TextField –

    A single-line text input field.

Attributes:

  • AnyEvent –

    Union type representing any event that can be processed by the app.

  • NextFunc –

    Type alias for the next function in the middleware chain.

  • AnyResponse –

    Union type representing any response that can be returned from handlers.

AnyEvent module-attribute 

AnyEvent = ActionEvent | WebhookEvent

Union type representing any event that can be processed by the app.

NextFunc module-attribute 

NextFunc = Callable[[AnyEvent], Awaitable[AnyResponse]]

Type alias for the next function in the middleware chain.

AnyResponse module-attribute 

AnyResponse = Message | Form | None

Union type representing any response that can be returned from handlers.

App 

App(
    *,
    token: str | None = None,
    middleware: list[Middleware] = [],
)

The main application class for building Frame.io integrations.

This class serves as the core of your integration. It is an ASGI-compatible application that listens for incoming HTTP POST requests from Frame.io, validates their signatures, and dispatches them to the appropriate handler functions that you register using decorators.

Attributes:

  • client (Client) –

    An authenticated API client for making calls back to the Frame.io API, available if an token was provided.

Parameters:

  • token

    (str | None, default: None ) –

    An optional access token obtained from the Adobe Developer Console. If provided, this token will be used to authenticate API calls made via the app.client property. It is highly recommended to load this from a secure source, such as an environment variable.

  • middleware

    (list[Middleware], default: [] ) –

    An optional list of middleware classes to process requests before they reach the handler.

Methods:

  • on_webhook –

    Decorator to register a function as a webhook event handler.

  • on_action –

    Decorator to register a function as a custom action handler.

  • __call__ –

    ASGI call interface to delegate to the underlying Starlette app.

client property 

client: Client

Provides access to an authenticated asynchronous API client.

This client can be used within your handler functions to make calls back to the Frame.io API to fetch more information or perform actions. The client is initialized lazily on its first access.

Example 
@app.on_webhook("file.ready", secret="...")
async def on_file_ready(event: WebhookEvent):
    # Use the client to fetch more details about the file
    file_details = await app.client.files.show(account_id=event.account_id, file_id=event.resource_id)
    print(file_details.data.name)

Returns:

  • Client –

    An instance of Frame.io Client, ready to make authenticated requests.

Raises:

  • RuntimeError –

    If the App was initialized without an token.

on_webhook 

on_webhook(event_type: str | list[str], secret: str)

Decorator to register a function as a webhook event handler.

This decorator registers an asynchronous function to be called whenever Frame.io sends a webhook event of the specified type(s). A webhook handler can only receive WebhookEvent and can only return a Message or None.

Example 
from frameio_kit import App, WebhookEvent

app = App()

@app.on_webhook(event_type="file.ready", secret="your-secret")
async def on_file_ready(event: WebhookEvent):
    # Handle the event
    pass

Parameters:

  • event_type
    (str | list[str]) –

    The Frame.io event type to listen for (e.g., "file.ready"). You can also provide a list of strings to register the same handler for multiple event types.

  • secret
    (str) –

    The mandatory signing secret obtained from the Frame.io Developer Console for this webhook. It is used to verify the authenticity of incoming requests.

on_action 

on_action(
    event_type: str,
    name: str,
    description: str,
    secret: str,
)

Decorator to register a function as a custom action handler.

This decorator connects an asynchronous function to a Custom Action in the Frame.io UI. The handler receives an ActionEvent and can return a Message, a Form for more input, or None.

Example 
from frameio_kit import App, ActionEvent

app = App()

@app.on_action(event_type="my_app.transcribe", name="Transcribe", description="Transcribe file", secret="your-secret")
async def on_transcribe(event: ActionEvent):
    # Handle the event
    pass

Parameters:

  • event_type
    (str) –

    A unique string you define to identify this action (e.g., "my_app.transcribe"). This is the type that will be present in the incoming payload.

  • name
    (str) –

    The user-visible name for the action in the Frame.io UI menu.

  • description
    (str) –

    A short, user-visible description of what the action does.

  • secret
    (str) –

    The mandatory signing secret generated when you create the custom action in Frame.io.

__call__ async 

__call__(scope: Scope, receive: Receive, send: Send)

ASGI call interface to delegate to the underlying Starlette app.

Client 

Client(
    *,
    base_url: str | None = None,
    token: str | Callable[[], str] | None = None,
    headers: dict[str, str] | None = None,
    timeout: float | None = None,
    follow_redirects: bool | None = True,
)

Bases: AsyncFrameio

Asynchronous HTTP client for interacting with the Frame.io v4 API.

This class provides access to all stable API endpoints and also contains a dedicated client for experimental features via the .experimental property.

Attributes:

  • experimental –

    An instance of ExperimentalFrameioClient for accessing endpoints that are in beta or under development.

Methods:

  • close –

    Gracefully closes the underlying httpx.AsyncClient session.

close async 

close() -> None

Gracefully closes the underlying httpx.AsyncClient session.

Account

Bases: BaseModel

Represents the account context, used in standard webhook payloads.

Attributes:

  • id (str) –

    The unique identifier (UUID) of the account.

ActionEvent

Bases: _BaseEvent

A custom action event payload, including user-submitted form data.

This model is used for handlers registered with @app.on_action. It differs from WebhookEvent by having a top-level account_id and including specific fields related to the action's lifecycle.

Attributes:

  • account_id (str) –

    The ID of the account where the event originated.

  • action_id (str) –

    The ID of the custom action that was triggered.

  • interaction_id (str) –

    A unique ID for a sequence of interactions, used to correlate steps in a multi-step custom action (e.g., a form submission).

  • data (dict[str, Any] | None) –

    A dictionary containing submitted form data. This will be None for the initial trigger of an action before a form is displayed. When a form is submitted, the keys of this dictionary will match the name of each form field.

resource_id property 

resource_id: str

A convenience property to directly access the resource's ID.

Returns:

  • str –

    The unique identifier (UUID) of the event's primary resource.

user_id property 

user_id: str

A convenience property to directly access the user's ID.

Returns:

  • str –

    The unique identifier (UUID) of the user.

project_id property 

project_id: str

A convenience property to directly access the project's ID.

Returns:

  • str –

    The unique identifier (UUID) of the project.

workspace_id property 

workspace_id: str

A convenience property to directly access the workspace's ID.

Returns:

  • str –

    The unique identifier (UUID) of the workspace.

Project

Bases: BaseModel

Represents the project context in which an event occurred.

Attributes:

  • id (str) –

    The unique identifier (UUID) of the project.

Resource

Bases: BaseModel

Represents the primary resource that an event pertains to.

Attributes:

  • id (str) –

    The unique identifier (UUID) of the resource.

  • type (Literal['file', 'folder', 'version_stack']) –

    The type of the resource (e.g., 'file', 'folder').

User

Bases: BaseModel

Represents the user who initiated the event.

Attributes:

  • id (str) –

    The unique identifier (UUID) of the user.

WebhookEvent

Bases: _BaseEvent

A standard webhook event payload from Frame.io.

This model is used for handlers registered with @app.on_webhook.

Attributes:

  • account (Account) –

    The account context object for the event.

resource_id property 

resource_id: str

A convenience property to directly access the resource's ID.

Returns:

  • str –

    The unique identifier (UUID) of the event's primary resource.

user_id property 

user_id: str

A convenience property to directly access the user's ID.

Returns:

  • str –

    The unique identifier (UUID) of the user.

project_id property 

project_id: str

A convenience property to directly access the project's ID.

Returns:

  • str –

    The unique identifier (UUID) of the project.

workspace_id property 

workspace_id: str

A convenience property to directly access the workspace's ID.

Returns:

  • str –

    The unique identifier (UUID) of the workspace.

account_id property 

account_id: str

A convenience property to directly access the account's ID.

Returns:

  • str –

    The unique identifier (UUID) of the account.

Workspace

Bases: BaseModel

Represents the workspace (formerly Team) in which an event occurred.

Attributes:

  • id (str) –

    The unique identifier (UUID) of the workspace.

Middleware

Base class for creating middleware in Frame.io integrations.

Middleware provides a powerful way to add cross-cutting concerns to your Frame.io integration without cluttering your handler functions. You can use middleware for logging, authentication, metrics collection, error handling, and more.

The Middleware base class provides three hooks you can override:

  • __call__: The main entry point that runs for every event (both webhooks and actions)
  • on_webhook: Runs only for webhook events
  • on_action: Runs only for custom action events
Example 
class TimingMiddleware(Middleware):
    async def __call__(self, event: AnyEvent, next: NextFunc) -> AnyResponse:
        start_time = time.monotonic()
        response = await next(event)
        duration = time.monotonic() - start_time
        print(f"Processed {event.type} in {duration:.2f}s")
        return response

app = App(middleware=[TimingMiddleware()])

Methods:

  • __call__ –

    The main entry point that runs for every event (both webhooks and actions).

  • on_webhook –

    Runs only for webhook events.

  • on_action –

    Runs only for custom action events.

__call__ async 

__call__(event: AnyEvent, next: NextFunc) -> AnyResponse

The main entry point that runs for every event (both webhooks and actions). This is where you implement logic that should apply universally.

Override this method when you need logic that should run on every single event, regardless of its type. This is perfect for universal concerns like:

  • Request timing and performance monitoring
  • Error handling and logging
  • Authentication and authorization
  • Request/response transformation

Parameters:

  • event
    (AnyEvent) –

    The event being processed (WebhookEvent or ActionEvent)

  • next
    (NextFunc) –

    Function to call the next middleware or handler in the chain

Returns:

  • AnyResponse –

    The response from the next middleware or handler, or None

Example 
async def __call__(self, event: AnyEvent, next: NextFunc) -> AnyResponse:
    # Code here runs before every event
    result = await next(event)  # Call the next middleware or handler
    # Code here runs after every event
    return result
Note

When you override __call__, you completely replace the base implementation. This means: - Without super(): The on_webhook and on_action methods will not be called - With super(): The original dispatch logic is preserved, so on_webhook and on_action will still be called

on_webhook async 

on_webhook(
    event: WebhookEvent, next: NextFunc
) -> AnyResponse

Runs only for webhook events.

Override this method when you need webhook-specific logic that doesn't apply to custom actions.

Parameters:

  • event
    (WebhookEvent) –

    The webhook event being processed

  • next
    (NextFunc) –

    Function to call the next middleware or handler in the chain

Returns:

  • AnyResponse –

    The response from the next middleware or handler, or None

Example 
async def on_webhook(self, event: WebhookEvent, next: NextFunc) -> AnyResponse:
    # Code here runs only for webhook events
    result = await next(event)
    return result

on_action async 

on_action(
    event: ActionEvent, next: NextFunc
) -> AnyResponse

Runs only for custom action events.

Override this method when you need action-specific logic that doesn't apply to webhooks.

Parameters:

  • event
    (ActionEvent) –

    The action event being processed

  • next
    (NextFunc) –

    Function to call the next middleware or handler in the chain

Returns:

  • AnyResponse –

    The response from the next middleware or handler, or None

Example 
async def on_action(self, event: ActionEvent, next: NextFunc) -> AnyResponse:
    # Code here runs only for action events
    result = await next(event)
    return result

CheckboxField

Bases: _BaseField

A checkbox input.

Example:

from frameio_kit import Form, CheckboxField

return Form(
    title="Confirm Action",
    fields=[CheckboxField(label="Overwrite existing file?", name="overwrite", value=False)]
)

Attributes:

  • type (Literal['checkbox']) –

    The field type, fixed to "checkbox".

  • value (bool | None) –

    An optional default state for the checkbox (True for checked).

Form

Bases: _UIResponse

A modal with a form to collect input from the user.

When returned from a handler, this model renders a form in the Frame.io UI. Upon submission, Frame.io sends another ActionEvent to your endpoint, this time populating the data attribute with the user's input.

Attributes:

  • fields (list[FormField]) –

    A list of one or more form field objects (e.g., TextField, SelectField) to be displayed in the form.

LinkField

Bases: _BaseField

A non-editable field that displays a URL with a "Copy" button.

This is useful for presenting a user with a link to an external resource that was generated as part of the action.

Example:

from frameio_kit import Form, LinkField

return Form(
    title="External Link",
    fields=[LinkField(label="External Link", name="external_link", value="https://www.example.com")]
)

Attributes:

  • type (Literal['link']) –

    The field type, fixed to "link".

  • value (str | None) –

    The URL to be displayed.

Message

Bases: _UIResponse

A simple message modal to display information to the user.

This is typically used as the final step in a custom action to confirm that an operation was successful or to provide information.

Example:

from frameio_kit import Message

return Message(title="Success", description="The action was successful.")

SelectField

Bases: _BaseField

A dropdown menu allowing the user to select one from a list of options.

Example:

from frameio_kit import Form, SelectField, SelectOption

PLATFORMS = [
    SelectOption(name="Twitter", value="twitter"),
    SelectOption(name="Instagram", value="instagram"),
]

return Form(
    title="Choose Platform",
    fields=[SelectField(label="Platform", name="platform", options=PLATFORMS)]
)

Attributes:

  • type (Literal['select']) –

    The field type, fixed to "select".

  • options (list[SelectOption]) –

    A list of SelectOption objects defining the choices.

  • value (str | None) –

    An optional default value to pre-select an option. This must match the value of one of the items in the options list.

SelectOption

Bases: _BaseField

Represents a single choice within a SelectField.

Attributes:

  • name (str) –

    The user-visible text for the option in the dropdown list.

  • value (str) –

    The actual value that will be sent back in the data payload if this option is selected.

TextareaField

Bases: _BaseField

A multi-line text input area, suitable for longer descriptions.

Example:

from frameio_kit import Form, TextareaField

return Form(
    title="Comment",
    fields=[TextareaField(label="Comment", name="comment", value="Enter your feedback...")]
)

Attributes:

  • type (Literal['textarea']) –

    The field type, fixed to "textarea".

  • value (str | None) –

    An optional default value to pre-populate the field.

TextField

Bases: _BaseField

A single-line text input field.

Example:

from frameio_kit import Form, TextField

return Form(
    title="Comment",
    fields=[TextField(label="Comment", name="comment", value="Enter your feedback...")]
)

Attributes:

  • type (Literal['text']) –

    The field type, fixed to "text".

  • value (str | None) –

    An optional default value to pre-populate the field.