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

# File Structure

> How a connector's files are organized — the main connector file, resource partials, and naming conventions.

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

**Naming conventions:**

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

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

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

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