> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# YAML Schema

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

## Top-level structure

```yaml theme={null}
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: { ... }
```

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`StackOne`</td>
      <td>Connector schema version, set to `1.0.0`.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>[`actions`](#actions)</td>
      <td>Actions the connector exposes.</td>
      <td>object\[]</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`authentication`](#authentication)</td>
      <td>Authentication methods the connector supports.</td>
      <td>object\[]</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`baseUrl`](#baseurl)</td>
      <td>Root URL for all API requests, with interpolation support.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>[`concurrency`](#concurrency)</td>
      <td>Request concurrency configuration for the connector.</td>
      <td>object</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`documentation`](#documentation)</td>
      <td>External documentation links for the connector.</td>
      <td>object</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`events`](#events)</td>
      <td>Event and webhook configuration for the connector.</td>
      <td>object</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`forkedFrom`</td>
      <td>Key of the connector this one was forked from.</td>
      <td>string</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`info`](#info)</td>
      <td>Connector metadata.</td>
      <td>object</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>[`mcp`](#mcp)</td>
      <td>MCP-specific configuration for the connector.</td>
      <td>object</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`rateLimit`](#ratelimit)</td>
      <td>Request rate-limit configuration for the connector.</td>
      <td>object</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`releaseStage`</td>
      <td>Maturity level of the connector.<br />Allowed: `preview`, `beta`, `ga`, `deprecated`, `internal`</td>
      <td>enum</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`resources`</td>
      <td>Source of information for the connector, usually a URL to the provider's documentation.</td>
      <td>string</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`scopeDefinitions`](#scopedefinitions)</td>
      <td>Requirements actions can depend on, keyed by name, such as OAuth scopes, pricing tiers, or feature flags.</td>
      <td>object</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

## actions

The operations the connector exposes, each with inputs, steps, and a result. See [actions](/connector-yaml-reference/yaml-schema/actions).

## authentication

An array of authentication methods (OAuth 2.0, custom/API key, and others). See [authentication](/connector-yaml-reference/yaml-schema/authentication).

## baseUrl

**Examples**

```yaml theme={null}
# 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'
```

<Warning>Individual actions can override baseUrl in their step parameters.</Warning>

## concurrency

Request concurrency configuration for the connector.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`mainMaxConcurrency`</td>
      <td>Maximum number of concurrent in-flight requests per linked account.</td>
      <td>number</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>[`subPools`](#concurrency-subpools)</td>
      <td>Per-URL-pattern concurrency overrides.</td>
      <td>object\[]</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

<AccordionGroup>
  <Accordion title="concurrency.subPools">
    Per-URL-pattern concurrency overrides.

    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`maxConcurrency`</td>
          <td>Maximum concurrent requests for the matched URLs.</td>
          <td>number</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`subPoolKey`</td>
          <td>Identifier for this concurrency sub-pool.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`urlPattern`</td>
          <td>URL pattern the sub-pool's limit applies to.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

**Examples**

```yaml theme={null}
concurrency:
  mainMaxConcurrency: 5
  subPools:
    - subPoolKey: reports
      urlPattern: '/reports'
      maxConcurrency: 1
```

## documentation

External documentation links for the connector.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[`references`](#documentation-references)</td>
      <td>External documentation links.</td>
      <td>object\[]</td>
      <td>Yes</td>
    </tr>
  </tbody>
</table>

<AccordionGroup>
  <Accordion title="documentation.references">
    External documentation links.

    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`description`</td>
          <td>Explains what the reference covers.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`title`</td>
          <td>Link text for the reference.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`url`</td>
          <td>URL of the referenced document.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

**Examples**

```yaml theme={null}
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](/connector-yaml-reference/yaml-schema/events).

## info

Connector metadata.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[`assets`](#info-assets)</td>
      <td>Visual assets for the connector.</td>
      <td>object</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>[`changelog`](#info-changelog)</td>
      <td>Description of what changed in this version.</td>
      <td>object</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`description`</td>
      <td>Brief one-line summary of the connector.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`details`</td>
      <td>Extended description of capabilities and limitations.</td>
      <td>string</td>
      <td>No</td>
    </tr>

    <tr>
      <td>`key`</td>
      <td>Unique lowercase identifier used in API calls and tool names.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`title`</td>
      <td>Human-readable provider name shown in Hub and Dashboard.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`version`</td>
      <td>Connector version following semantic versioning.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>
  </tbody>
</table>

<AccordionGroup>
  <Accordion title="info.assets">
    Visual assets for the connector.

    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`icon`</td>
          <td>URL to the provider logo.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="info.changelog">
    Description of what changed in this version.

    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`labels`</td>
          <td>Tags categorizing the changelog entry for filtering.</td>
          <td>string\[]</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`summary`</td>
          <td>Human-readable summary of the changes in this version.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

### 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](/connector-building/connector-versioning)

**Examples**

```yaml theme={null}
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.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`instructions`</td>
      <td>Guidance text surfaced to MCP clients.</td>
      <td>string</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

## 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.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`mainRatelimit`</td>
      <td>Maximum requests per second for each linked account, across all of the connector's endpoints.</td>
      <td>number</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>[`mappedRateLimitErrors`](#ratelimit-mappedratelimiterrors)</td>
      <td>Provider responses that should be treated as rate-limit signals.</td>
      <td>object\[]</td>
      <td>No</td>
    </tr>

    <tr>
      <td>[`subPools`](#ratelimit-subpools)</td>
      <td>Per-URL-pattern rate limit overrides.</td>
      <td>object\[]</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

<AccordionGroup>
  <Accordion title="rateLimit.mappedRateLimitErrors">
    Provider responses that should be treated as rate-limit signals.

    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`errorMessage`</td>
          <td>Provider error message identifying a rate-limit error.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`errorMessagePath`</td>
          <td>Path to the error message in the response body.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`errorStatus`</td>
          <td>HTTP status code indicating a rate-limit error.</td>
          <td>number</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`retryAfterPath`</td>
          <td>Path to the retry-after value within the response headers, not the body.</td>
          <td>string</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`retryAfterUnit`</td>
          <td>Unit the retry-after value is expressed in.<br />Allowed: `seconds`, `milliseconds`, `date`</td>
          <td>enum</td>
          <td>No</td>
        </tr>

        <tr>
          <td>`retryAfterValue`</td>
          <td>Fixed delay to wait before retrying.</td>
          <td>number</td>
          <td>No</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="rateLimit.subPools">
    Per-URL-pattern rate limit overrides.

    <table>
      <colgroup>
        <col width="210" />

        <col width="400" />

        <col width="90" />

        <col width="90" />
      </colgroup>

      <thead>
        <tr>
          <th>Field</th>
          <th>Description</th>
          <th>Type</th>
          <th>Required</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>`rateLimit`</td>
          <td>Maximum requests per second for the matched URLs.</td>
          <td>number</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`subPoolKey`</td>
          <td>Identifier for this rate-limit sub-pool.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>

        <tr>
          <td>`urlPattern`</td>
          <td>URL pattern the sub-pool's limit applies to.</td>
          <td>string</td>
          <td>Yes</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

**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**

```yaml theme={null}
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.

<table>
  <colgroup>
    <col width="210" />

    <col width="400" />

    <col width="90" />

    <col width="90" />
  </colgroup>

  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
      <th>Type</th>
      <th>Required</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`description`</td>
      <td>Explains what this scope grants.</td>
      <td>string</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>`includes`</td>
      <td>Another scope this scope implies.</td>
      <td>string</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

**Examples**

```yaml theme={null}
scopeDefinitions:
  employees:read:
    description: Read employee data
  employees:write:
    description: Create and update employee records
    includes: employees:read
```

## Related

<CardGroup cols={2}>
  <Card title="File Structure" icon="book" href="/connector-yaml-reference/file-structure">
    How connector files and partials are organized.
  </Card>

  <Card title="Step Functions" icon="book" href="/connector-yaml-reference/step-functions/overview">
    The step functions actions are built from.
  </Card>
</CardGroup>