API Reference

Automation Coming soon

The workspace-level API - workflow executions, deploying a code-based project, and pulling one from git. Not yet documented here.

Embedded

The public REST API your application calls to manage and run integrations on behalf of your end users.

Each embedded resource is reachable two ways, and the reference documents them separately because the credential decides which one you can use.

Backend - API Key

Called from your own server. The connected user is named by the {externalUserId} path segment.

• Actions - execute a component action for a connected user.
• Tools - list a connected user's available tools, and execute one.
• Integrations - the integrations available to your customers.
• Integration Instances - a connected user's instance of an integration.
• Instance Workflows - enable, disable and configure an instance's workflows.
• Connections - list a connected user's connections.
• Connected Users - update a connected user.
• User Workflows - a connected user's own workflows, including generation from a prompt.
• Workflow Catalog - the catalog projects available to connected users.
• Workflow Executions - fetch a tenant's workflow executions. Served by the internal API rather than a public spec, so it has no reference page; read executions in the ByteChef admin UI.
• Tool Invocations - fetch a connected user's tool and action invocation history. No public spec yet, so it has no reference page.

Frontend - Signing Key JWT

Called from the browser with a short-lived token your backend signs. The connected user comes from the token's sub claim, so these paths carry no user id.

• Integrations - the integrations available to the signed-in user.
• Integration Instances - their instance of an integration.
• Instance Workflows - enable, disable and configure that instance's workflows.
• Connections - list their connections.
• Connected Users - update the signed-in user.
• User Workflows - their own workflows, including generation from a prompt.
• Workflow Catalog - the catalog projects available to them.
• App Events - fire an App Event to start every subscribed workflow.
• Request Trigger - execute a single workflow synchronously and return its result.

Platform Coming soon

Deploying a custom component to the platform. Not yet documented here.

---

Base URL

Every operation path you see on a reference page is relative to /api/embedded/v1. Prefix it with that, then with your ByteChef host - e.g. https://your-bytechef-host.example.com/api/embedded/v1.

---

Authentication

Every request carries a bearer token in the Authorization header, and there are two kinds.

An API Key authenticates you. It is the general ByteChef credential - the Automation and Platform APIs take one too - and on the embedded API it acts for whichever connected user the {externalUserId} path segment names.

A Signing Key JWT is specific to the embedded API. It authenticates one of your end users directly from the browser: your backend signs a short-lived token whose sub claim is that user, so the operations it reaches carry no user id in their path.

That is what the two sections of this reference correspond to:

It also explains why the paths differ. An API Key says nothing about which of your end users a call is for, so those operations carry the id in the path. A JWT already names the user, so its operations do not - which in turn means an API Key cannot be used against them: there would be no user to act for, and the request is rejected.

Actions and Tools are the exception that proves the rule. Their paths carry {externalUserId}, so either credential resolves a user and both are accepted; they are listed under Backend because that is how they are normally called.

Mint frontend tokens as described in Installing the SDK

• the private key never reaches the browser, and the token is short-lived. See Signing Keys and Embedded API Keys for issuing each credential.

Pass an optional X-Environment header (DEVELOPMENT, STAGING, or PRODUCTION) to scope the request to a specific environment. If omitted, ByteChef uses PRODUCTION.