one-integrations

Working with third-party apps through One

One exposes every connected app through three tools. No matter how many apps or actions the user has connected, it stays three tools, so finding is how you get to an action rather than reading a giant tool list.

The loop

Follow it in order. Skipping a step is where these calls fail.

1. List. Call list_one_integrations once at the start of a task. It tells you which platforms the user actually has connected and what you are allowed to run on each.
2. Find. Call find_one_actions once for the whole task, with one requests entry per operation, on any platforms: the platform and an intent naming the operation alone ("send an email", "list paid invoices"), not its data (no IDs, names or message text). Add a task: the whole job in one line, in general terms. For each intent it returns the action to use with its documentation, sometimes actions also needed beside it, sometimes a substitute to use instead (one or the other, never both), and a few alternatives.
3. Read the documentation of each action you will run, every time, before you execute it. This is the step agents skip and it is the step that prevents the failure. A large document comes back as a digest that names what it left out: call find_one_actions again with load: [{ "action_id": "...", "section": "..." }] for a missing section, "full": true for the whole document, or an alternative's action_id for its documentation.
4. Execute. Call execute_one_action with parameters copied from the documentation.

Never guess parameters

The documentation find_one_actions returns has the actual schema: required fields, exact names, types, enum values, where each value belongs (path, query, body, header). Guessing a field name that looks obvious produces a 400 from the platform, or worse, a 200 that wrote the wrong thing.