File Structure
Connectors are organized into a main connector file and (optionally) partial files for each resource:connectors/{provider}/
├── {provider}.connector.s1.yaml # Main connector (authentication, metadata)
└── {provider}.{resource}.s1.partial.yaml # Actions 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.StackOne: 1.0.0
info:
title: Provider Name
key: provider
version: 1.0.0
assets:
icon: https://stackone-logos.com/api/provider/filled/png
description: Brief description of the provider
baseUrl: https://api.provider.com/v1
rateLimit:
mainRatelimit: 10 # Requests per second
context: "Provider API documentation: https://api.provider.com/docs"
authentication:
- custom:
# ... authentication config
actions:
- $ref: provider.users
- $ref: provider.files
Complete Example
# provider.connector.s1.yaml
StackOne: 1.0.0
info:
title: Acme HR
key: acme_hr
version: 1.0.0
assets:
icon: https://stackone-logos.com/api/acme_hr/filled/png
description: HR management platform
baseUrl: https://api.acme.com/v2
rateLimit:
mainRatelimit: 10
authentication:
- custom:
type: custom
label: API Key
authorization:
type: bearer
token: $.credentials.apiKey
configFields:
- key: apiKey
label: API Key
type: password
required: true
secret: true
environments:
- key: production
name: Production
testActionsIds:
- list_employees
actions:
- $ref: acme_hr.employees
# provider.employees.s1.partial.yaml
- actionId: list_employees
categories:
- hris
actionType: custom
label: List Employees
description: Get all employees with pagination
context: https://api.acme.com/docs/employees
inputs:
- name: page_size
type: number
in: query
required: false
description: Results per page (max 100)
- name: status
type: string
in: query
required: false
description: Filter by status (active, inactive)
steps:
- stepId: fetch_employees
stepFunction:
functionName: paginated_request
parameters:
url: /employees
method: get
response:
dataKey: data
nextKey: pagination.next_cursor
iterator:
key: cursor
in: query
args:
- name: limit
value: '{{inputs.page_size || 100}}'
in: query
- name: status
value: '{{inputs.status}}'
in: query
condition: '{{present(inputs.status)}}'
result:
data: $.steps.fetch_employees.output.data
- actionId: get_employee
categories:
- hris
actionType: custom
label: Get Employee
description: Get employee by ID
context: https://api.acme.com/docs/employees/{id}
inputs:
- name: id
type: string
in: path
required: true
description: Employee ID
steps:
- stepId: fetch_employee
stepFunction:
functionName: request
parameters:
url: /employees/${inputs.id}
method: get
result:
data: $.steps.fetch_employee.output.data