YAML Schema

Complete reference for all connector YAML properties with examples and impact analysis.

Top-level structure

StackOne: 1.0.0
actions: [ ... ]
authentication: [ ... ]
baseUrl: 'https://api.provider.com'
concurrency: { ... }
documentation: { ... }
events: { ... }
forkedFrom: acme_hris
info: { ... }
mcp: { ... }
rateLimit: { ... }
releaseStage: ga
resources: 'https://api.provider.com/docs'
scopeDefinitions: { ... }

Field	Description	Type	Required
StackOne	Connector schema version, set to 1.0.0.	string	Yes
actions	Actions the connector exposes.	object[]	No
authentication	Authentication methods the connector supports.	object[]	No
baseUrl	Root URL for all API requests, with interpolation support.	string	Yes
concurrency	Request concurrency configuration for the connector.	object	No
documentation	External documentation links for the connector.	object	No
events	Event and webhook configuration for the connector.	object	No
forkedFrom	Key of the connector this one was forked from.	string	No
info	Connector metadata.	object	Yes
mcp	MCP-specific configuration for the connector.	object	No
rateLimit	Request rate-limit configuration for the connector.	object	No
releaseStage	Maturity level of the connector. Allowed: preview, beta, ga, deprecated, internal	enum	No
resources	Source of information for the connector, usually a URL to the provider’s documentation.	string	No
scopeDefinitions	Requirements actions can depend on, keyed by name, such as OAuth scopes, pricing tiers, or feature flags.	object	No

actions

The operations the connector exposes, each with inputs, steps, and a result. See actions.

authentication

An array of authentication methods (OAuth 2.0, custom/API key, and others). See authentication.

baseUrl

Examples

# Static URL
baseUrl: 'https://api.bamboohr.com/api/gateway.php'

# Dynamic URL with credentials:
baseUrl: 'https://api.bamboohr.com/api/gateway.php/${credentials.subdomain}/v1'

Individual actions can override baseUrl in their step parameters.

concurrency

Request concurrency configuration for the connector.

Field	Description	Type	Required
mainMaxConcurrency	Maximum number of concurrent in-flight requests per linked account.	number	Yes
subPools	Per-URL-pattern concurrency overrides.	object[]	No

concurrency.subPools

Per-URL-pattern concurrency overrides.

Field	Description	Type	Required
maxConcurrency	Maximum concurrent requests for the matched URLs.	number	Yes
subPoolKey	Identifier for this concurrency sub-pool.	string	Yes
urlPattern	URL pattern the sub-pool’s limit applies to.	string	Yes

Examples

concurrency:
  mainMaxConcurrency: 5
  subPools:
    - subPoolKey: reports
      urlPattern: '/reports'
      maxConcurrency: 1

documentation

External documentation links for the connector.

Field	Description	Type	Required
references	External documentation links.	object[]	Yes

documentation.references

External documentation links.

Field	Description	Type	Required
description	Explains what the reference covers.	string	No
title	Link text for the reference.	string	Yes
url	URL of the referenced document.	string	Yes

Examples

documentation:
  references:
    - title: API reference
      url: https://api.acme.com/docs
      description: Full REST API documentation.

events

Webhook and event configuration for the connector. See events.

info

Connector metadata.

Field	Description	Type	Required
assets	Visual assets for the connector.	object	Yes
changelog	Description of what changed in this version.	object	No
description	Brief one-line summary of the connector.	string	Yes
details	Extended description of capabilities and limitations.	string	No
key	Unique lowercase identifier used in API calls and tool names.	string	Yes
title	Human-readable provider name shown in Hub and Dashboard.	string	Yes
version	Connector version following semantic versioning.	string	Yes

info.assets

Visual assets for the connector.

Field	Description	Type	Required
icon	URL to the provider logo.	string	Yes

info.changelog

Description of what changed in this version.

Field	Description	Type	Required
labels	Tags categorizing the changelog entry for filtering.	string[]	No
summary	Human-readable summary of the changes in this version.	string	Yes

info.assets.icon

Requirements:

• 24x24 pixels minimum
• SVG or PNG format
• Transparent background preferred
• Hosted on HTTPS

info.description

Best practices:

• Keep under 200 characters
• Mention key capabilities
• Include category context (HRIS, CRM, etc.)

info.version

See Connector Versioning

Examples

info:
  title: Acme HRIS
  key: acme_hris
  version: 1.0.0
  description: HRIS connector for Acme covering employees, departments, and time-off.
  assets:
    icon: https://stackone-logos.com/api/acme/filled/png

mcp

MCP-specific configuration for the connector.

Field	Description	Type	Required
instructions	Guidance text surfaced to MCP clients.	string	No

rateLimit

The runtime tracks requests per linked account and throttles when limits are reached. Requests exceeding the limit are queued and retried with exponential backoff.

Request rate-limit configuration for the connector.

Field	Description	Type	Required
mainRatelimit	Maximum requests per second for each linked account, across all of the connector’s endpoints.	number	Yes
mappedRateLimitErrors	Provider responses that should be treated as rate-limit signals.	object[]	No
subPools	Per-URL-pattern rate limit overrides.	object[]	No

rateLimit.mappedRateLimitErrors

Provider responses that should be treated as rate-limit signals.

Field	Description	Type	Required
errorMessage	Provider error message identifying a rate-limit error.	string	Yes
errorMessagePath	Path to the error message in the response body.	string	No
errorStatus	HTTP status code indicating a rate-limit error.	number	Yes
retryAfterPath	Path to the retry-after value within the response headers, not the body.	string	No
retryAfterUnit	Unit the retry-after value is expressed in. Allowed: seconds, milliseconds, date	enum	No
retryAfterValue	Fixed delay to wait before retrying.	number	No

rateLimit.subPools

Per-URL-pattern rate limit overrides.

Field	Description	Type	Required
rateLimit	Maximum requests per second for the matched URLs.	number	Yes
subPoolKey	Identifier for this rate-limit sub-pool.	string	Yes
urlPattern	URL pattern the sub-pool’s limit applies to.	string	Yes

Best practices

• Set slightly below provider’s documented limit
• Check provider API docs for per-endpoint limits
• Some providers have different limits for different endpoints

Examples

rateLimit:
  mainRatelimit: 10
  subPools:
    - subPoolKey: search
      urlPattern: '/search'
      rateLimit: 2
  mappedRateLimitErrors:
    - errorStatus: 429
      errorMessage: Too Many Requests
      retryAfterPath: "$['retry-after']"
      retryAfterUnit: seconds

scopeDefinitions

Requirements actions can depend on, keyed by name, such as OAuth scopes, pricing tiers, or feature flags.

Field	Description	Type	Required
description	Explains what this scope grants.	string	Yes
includes	Another scope this scope implies.	string	No

Examples

scopeDefinitions:
  employees:read:
    description: Read employee data
  employees:write:
    description: Create and update employee records
    includes: employees:read

Related

File Structure

How connector files and partials are organized.

Step Functions

The step functions actions are built from.