File Structure
Connectors are organized into a main connector file and (optionally) partial files for each resource:- Use kebab-case for file names
- Reference partials in the main file using
$ref: provider.resource - Add references in alphabetical order (not required, but recommended for readability)
Main Connector File
The main connector file defines metadata, authentication, and references to action partials.Info Section
| Field | Required | Description |
|---|---|---|
title | Yes | Display name shown in the StackOne Hub and dashboard |
key | Yes | Unique lowercase identifier used in action names (e.g., bamboohr_list_employees) |
version | Yes | Semantic version for tracking connector changes |
assets.icon | No | URL to provider logo (displayed in Hub and dashboard) |
description | No | Brief description for documentation and AI context |
When to use each field
When to use each field
title: User-facing name. Use the official provider name (e.g., “BambooHR” not “Bamboo HR”)key: Machine-readable identifier. Must be lowercase with underscores. Cannot be changed after deployment without breaking existing integrationsversion: Increment when making changes. Use semantic versioning: major.minor.patchassets.icon: Usehttps://stackone-logos.com/api/{key}/filled/pngfor consistent stylingdescription: Keep concise. Used by AI agents for context when discovering connectors
Base URL
ThebaseUrl defines the root URL for all API requests. It supports credential interpolation for providers with dynamic domains.
When to use dynamic baseUrl
When to use dynamic baseUrl
Use credential interpolation when the provider requires:
- Customer-specific subdomains: Many B2B SaaS products use
{company}.provider.comURLs - Region selection: Some providers have separate endpoints per region (US, EU, APAC)
- Environment switching: Sandbox vs production endpoints
configFields in your authentication config. These are fields your customer fills in when connecting their account.Authentication
Authentication is defined once in the main connector file. All actions inherit it.Setup vs Config Fields
| Field Type | Who Fills It | When | Example |
|---|---|---|---|
setupFields | You (the developer) | Dashboard integration config | Client ID, Client Secret, Scopes |
configFields | Your customer | Hub account connection | API Token, Subdomain |
Choosing between setupFields and configFields
Choosing between setupFields and configFields
Use
setupFields for:- OAuth client credentials (Client ID, Client Secret)
- Scopes that you control
- API keys that belong to your app, not the end user
- Values you configure once in the StackOne dashboard
configFields for:- Customer’s own API tokens or keys
- Customer-specific identifiers (subdomain, account ID, workspace ID)
- Any value that differs per customer connection
- Values the customer enters in the Hub when linking their account
secret: true: Masks the field value and encrypts storage (use for tokens, keys, passwords)required: true: Field must be filled before connection can completeplaceholder: Shows example format without exposing real valuestooltip: Additional help text shown on hover
API Key Authentication
Basic Authentication
Custom Headers
OAuth 2.0
Actions
Actions define the operations your connector can perform. Each action consists of metadata, inputs, steps, and result configuration.Action Structure
| Field | Required | Description |
|---|---|---|
actionId | Yes | Unique identifier within the connector. Forms the action name: {connector_key}_{actionId} |
categories | Yes | Array of verticals this action belongs to (see Categories) |
actionType | Yes | Identifies the type of the action (list, get, create, update, delete, custom) |
schema | Conditional | Required for unified actions. Specifies which StackOne schema to map to |
label | Yes | Human-readable name shown in Actions Explorer and AI tool descriptions |
description | Yes | Explains what the action does. Used by AI agents for tool selection |
context | No | URL to provider API docs. Helps AI agents understand the action |
entrypointUrl | No | Alternative to defining URL in steps. The main endpoint path |
entrypointHttpMethod | No | Alternative to defining method in steps. HTTP method to use |
How these fields affect your action
How these fields affect your action
actionId: Keep it descriptive and follow the pattern{verb}_{resource}(e.g.,list_users,get_employee,create_candidate). Cannot be changed after deployment.categories: Determines where the action appears in the Actions Explorer. An action can belong to multiple categories.actionType: Choosingcustomis fastest since no schema mapping is needed. Use unified types (list,get, etc.) when you want cross-provider compatibility.schema: Must match a StackOne schema name (e.g.,users,employees,candidates). Only required whenactionTypeis unified.label+description: These appear in the Actions Explorer and are sent to AI agents. Write them for humans, not machines.context: Adding the provider’s API doc URL helps the Builder Agent and AI tools understand edge cases.
Action Types
Action types define the operations your action performs. All action types can be used with or without schema mapping.| Type | Description |
|---|---|
list | Retrieve multiple records, typically with pagination |
get | Retrieve a single record by identifier |
create | Create a new resource |
update | Modify an existing resource |
delete | Remove a resource |
custom | Provider-specific operation that doesn’t fit standard CRUD patterns |
refresh_token | Internal OAuth token refresh (use with internal category) |
- Add
schemafield to map provider data to StackOne’s standardized schemas (e.g.,schema: employees) - Without
schema, the action returns provider data as-is - Unified actions with schemas require
fieldConfigsfor field mapping (see Field Configs)
Categories
Categories classify actions by API vertical, making it easy to filter and discover actions across your connector ecosystem.| Category | Description |
|---|---|
hris | HR Information Systems (employees, time-off, payroll) |
ats | Applicant Tracking (candidates, jobs, applications) |
crm | Customer Relationship Management (contacts, deals) |
lms | Learning Management (courses, completions) |
documents | Document Management (files, folders) |
ticketing | Ticketing/Projects (issues, tasks) |
messaging | Communication (messages, channels) |
iam | Identity & Access (users, groups, roles) |
accounting | Accounting & Finance (invoices, accounts) |
internal | Internal only, not exposed in API |
Inputs
Define parameters your action accepts:string, number, boolean, datetime_string, object
Input locations:
path: URL path parameter (/users/${inputs.id})query: Query string (?status=active)body: Request body fieldheaders: HTTP header
Choosing the right input location
Choosing the right input location
Use
path for:- Resource identifiers (user ID, file ID)
- Required route segments that the API expects in the URL
- Values that identify which resource to access
query for:- Optional filters and search parameters
- Pagination controls (page, limit, cursor)
- Sorting and field selection
- Values that modify how to retrieve resources
body for:- Data being created or updated (POST, PUT, PATCH)
- Complex objects and nested structures
- Bulk operations with multiple items
headers for:- Request-specific configuration (content type, accept)
- API versioning (
X-API-Version: 2) - Custom provider headers not covered by authentication
path (for IDs) or query (for filters). Body inputs are mainly for write operations.Step Functions
Step functions are the building blocks of actions. Each step performs one operation.Choosing the right step function
Choosing the right step function
| Scenario | Use |
|---|---|
| Single API call (get user, create record) | request |
| List endpoint with cursor pagination | paginated_request |
| List endpoint with offset/page pagination | request + manual cursor handling |
| Transform provider data to output schema | map_fields |
| Convert field types after mapping | typecast |
| Merge results from multiple API calls | group_data |
- GET single resource:
request→result - LIST with pagination:
paginated_request→result - Unified action:
request→map_fields→typecast→result - Multi-source data:
request(x2) →group_data→result
request - HTTP Requests
Make a single HTTP request to the provider API.
| Parameter | Description |
|---|---|
url | Endpoint path (supports interpolation) |
method | get, post, put, patch, delete |
args | Request arguments (headers, query, body) |
authorization | Override auth for this request |
response.collection | Whether response is an array |
response.dataKey | Extract data from this key |
response.indexField | Field to use as index |
customErrors | Remap provider error responses |
paginated_request - Cursor Pagination
Automatically fetches all pages of results using cursor-based pagination. StackOne handles cursor tracking, page assembly, and continuation logic.
- Makes initial request without cursor
- Extracts results from
response.dataKey - Checks
response.nextKeyfor continuation cursor - If cursor exists, makes next request with cursor in
iterator.key - Repeats until no cursor is returned
- Returns combined results from all pages
| Parameter | Required | Description |
|---|---|---|
response.dataKey | Yes | JSONPath to the results array (e.g., data, results, items) |
response.nextKey | Yes | JSONPath to the next cursor value (e.g., pagination.next_cursor, meta.nextPageToken) |
iterator.key | Yes | Parameter name for passing cursor to API |
iterator.in | Yes | Location: query for URL params, body for request body |
map_fields - Transform Data
Transform provider response data into your output schema. Essential for unified actions that map to StackOne schemas.
How it works:
- Takes input data from
dataSource(typically a previous step’s output) - For each field in
fields, evaluates theexpressionagainst each record - Converts the result to the specified
type - For arrays, processes each item individually
- Returns transformed data with the new field structure
- Enum Mapping
- Nested Objects
- Concatenation
Map provider values to standardized enum values:
| Parameter | Required | Description |
|---|---|---|
dataSource | Yes | JSONPath to input data (e.g., $.steps.fetch_users.output.data) |
fields | Yes | Array of field mapping configurations |
| Option | Description |
|---|---|
targetFieldKey | Output field name |
expression | JSONPath or JEXL expression to extract value |
type | string, number, boolean, datetime_string, enum, object |
array | Whether field is an array (default: false) |
enumMapper | Map provider values to standardized enums |
properties | Nested field configs for object types |
custom | Mark as custom field outside schema (default: false) |
hidden | Exclude from output (default: false) |
typecast - Type Conversion
Apply type conversions to data. Used for unified actions.
group_data - Combine Results
Merge data from multiple steps.
Expression Syntax
Falcon supports three expression formats for dynamic values.JSONPath (Preferred)
Direct data access. Use for any direct reference.String Interpolation (${...})
Use for embedding values within strings.
JEXL Expressions ('{{...}}')
Use for conditional logic and transformations. Must be in single quotes.
present(value)- Returns true if value existsempty(value)- Returns true if value is empty/null
Conditional Arguments
Include arguments only when conditions are met:Result
Define the action’s response output. Read operations:Field Configs (Unified Actions)
For unified actions,fieldConfigs map provider response to StackOne schema:
Custom Enum Matchers
For large enums (like file formats with 1200+ values), use built-in matchers:country_alpha2code_by_alpha2codedocument_file_format_from_extension