Getting Started

Building a Maven App and using the API

To use Maven APIs, all calls must be made within the context of a Maven App. Each app has an app ID and secret for authentication.

Maven Apps must be installed on Agents from the App Marketplace. Apps can only call APIs for Agents on which they are installed, ensuring a secure interaction model.

Making API Calls

Using the app ID and secret, you can call Maven REST APIs directly via CURL or any of our SDKs. The API reference includes examples of every call.

Lightweight Integrations

For lightweight integrations, we recommend using the Maven App serverless platform, which provides:

  • Automatic URL: Maven apps are automatically provided with a URL for handling incoming requests.
  • No Deployments: Serverless apps do not require deployments; authorization is handled automatically by the platform.

Handling Event Triggers and Actions

To handle event triggers or actions, some serverless code is required. The Maven app must implement the defined TypeScript interface to respond to platform events. For those who primarily use their own platform this serverless code can be minimal as it can call out to any third-party API.

In-Browser Code Editing

The developer portal provides a code editor for in-browser editing of serverless app code. This code can optionally be synced to a GitHub repository.

App Types

Maven apps currently support the following capabilities:

  • Knowledge Apps Create knowledge bases and documents based on external content.
  • Action Apps Enable the Maven AI agent to call external APIs based on user questions. These apps register supported actions and handle API calls within their serverless implementation, returning responses in markdown.
  • Conversation Apps Provide custom question surface integrations. They can transform Maven API responses into a custom format or build a custom chat UI specific to your company. Conversation APIs can support direct user questions or suggest answers for copilot integrations.
  • User Apps Provide user data to Maven. Maven aggregates user data across all app integrations to provide a holistic view of users and enable cross-app communication.
  • Event Trigger Apps Allow an app to respond to Maven platform events (e.g. feedback created)

Working with Entity IDs

All objects in the Maven APIs have an ID represented by the EntityId class.

When creating new objects in Maven, the only required field in an EntityId is the referenceId string. This string is globally unique within the Maven platform when combined with the appId, organizationId, agentId, and type — all of which are inferred from the API creation call.

Reference IDs for Conversations or Knowledge bases often represent an ID from another system that is integrating with Maven. For Conversations that do not reference an external system, we recommend using a UUID. In TypeScript, this can be generated using crypto.randomUUID().

With Actions or Event triggers, it’s recommended to use memorable names that are easy to read in code, such as an action ID of get-balance.