DocsCreating Integrations
How to define a custom integration with operations, authentication methods, and data types that connect your blueprint to external APIs.
Integrations are defined within blueprints. Each integration describes an external API — its base URL, available endpoints, authentication requirements, and data schemas.
Defining an integration
An integration definition includes:
Metadata
- Name — unique identifier within the blueprint
- Title — human-readable display name
- Version — integration version
- Kind — protocol type (
rest,graphql,grpc,soap,custom) - Base URL — the root URL for all operations (for example,
https://api.example.com/v2)
Default parameters
Parameters that apply to all operations in the integration. Common uses:
- API version headers (
Accept: application/vnd.api+json) - Default query parameters (
format=json) - Custom headers required by all endpoints
Operations
Each operation represents an API endpoint:
| Property | Description |
|---|---|
| ID | Unique identifier within the integration |
| Name | Human-readable operation name |
| Method | HTTP method (GET, POST, PUT, DELETE, PATCH) |
| Path | URL path relative to the base URL (supports path parameters like /users/{userId}) |
| Params | Input parameters with their location (path, query, header, body), type, and validation |
| Output | Response definitions including status code matching and transforms |
| Auth | Authentication override — _inherit (use default), _noauth, or a specific auth method name |
Parameter locations
| Location | Where the parameter is sent |
|---|---|
| path | Inserted into the URL path (for example, /users/{userId}) |
| query | Added as a URL query parameter |
| header | Sent as an HTTP header |
| body | Sent in the request body |
Output transforms
Each operation can define transforms that extract and reshape the API response:
- Status matching — different output definitions for different HTTP status codes
- JSONPath extraction — extract specific fields from the response body
- Schema mapping — map response fields to a typed output schema
Auth methods
Each authentication method defines how credentials are sent:
| Kind | How it works |
|---|---|
| basic | Username and password sent as HTTP Basic Auth |
| bearer | Token sent in Authorization: Bearer {token} header |
| apikey | Key sent as a header, query parameter, or cookie |
| oauth2 | Full OAuth2 flow with authorization URL, token URL, and scopes |
| custom | Custom authentication logic with parameterized credential fields |
Auth methods define a params schema that specifies what credential fields are required (for example, apiKey, clientId, clientSecret). When users create connections, they provide values for these fields.
Data types
Shared JSON schemas that can be referenced across operations. For example, a Contact data type used in both createContact and listContacts operations.
Automatic sync
When you save an integration, the platform automatically:
- Creates actions for each operation. The action UID is deterministically generated from the integration UID and operation ID, ensuring stable references.
- Registers auth methods on the blueprint, making them available for connection creation.
- Creates event channels and definitions for any defined channels.
- Registers data types on the blueprint.
You can immediately use the generated actions in flows and agent configurations.
Execution
When an integration action is called, the platform's integration engine handles execution:
- Builds the HTTP request from the operation definition (method, URL, headers, body)
- Maps input parameters to their configured locations (path, query, header, body)
- Injects authentication credentials from the specified connection
- Sends the request
- Applies output transforms to the response
- Returns the transformed result
The caller does not need to know the details of the HTTP request — they interact with a typed action that has input and output schemas.
Related concepts
- OpenAPI Import — importing existing API specs instead of defining manually
- Connections — providing credentials for integration auth methods
- Event Channels — receiving events from external systems
- Actions — how integration operations become callable actions
Integrations
Integrations bind external APIs to the platform. They define operations, authentication methods, event channels, and data types that become available as actions within blueprints.
OpenAPI Import
Import existing OpenAPI 3.x specifications to automatically create integrations with operations, authentication methods, and schemas.