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

# Connectors

> Pre-built integrations that allow your workflows and agents to interact with external services and data sources. They handle authentication, data formatting, and API communication so you can focus on building fan experiences.

Each connector is designed to be easily integrated into your workflows with minimal configuration. Connectors come in two main types:

* **Python-based connectors** (`pyscript`): Implemented as Python modules with defined functions
* **REST API connectors** (`restapi`): Configured using JSON specifications for API endpoints

## Connector Structure

A typical connector consists of:

1. A configuration file (`.yml`) that defines the connector's name, description, and available commands
2. An implementation file (`.py`) for Python-based connectors or (`.json`) for REST API connectors
3. An installation file (`_install.yml`) that specifies how the connector should be installed

## Available Connectors

The following connectors are available for use in your workflows:

### Language Models

**Groq hosted models**

* High-performance AI inference.
* *Instant access*

**OpenAI models**

* Advanced language models.
* *Instant access*

### Sports Data

**FastF1**

* Open-source Formula 1 data provider.
* *Instant access*

**MLB StatsAPI**

* Comprehensive MLB baseball data including teams, seasons, schedules, standings, and stats.
* *Instant access*

**Sportradar**

* Comprehensive real-time sports data provider.
* *Requires API key*

### Betting & Odds

**bwin Sports API**

* Real-time betting odds and insights.
* *Requires API key*

**TallySight**

* Real-time odds widgets.
* *Requires API key*

### Media Generation

**GPT Image 1**

* AI image generation.
* *Instant access*

<Note>
  Each token from GPT Image 1 counts as 2x on token execution counts.
</Note>

**Stability AI**

* AI image generation.
* *Requires API key*

**ElevenLabs**

* Generate lifelike spoken audio.
* *Requires API key*

**HeyGen**

* AI Avatars video generation.
* *Requires API key*

### Content Processing

**Docling**

* Document processing, including advanced PDF parsing.
* *Instant access*

**Twelve Labs**

* Video understanding platform.
* *Requires API key*

### Web Search Retrieval

**Perplexity**

* Real-time web search powered by AI.
* *Requires API key*

**Exa**

* Powerful search to power your applications.
* *Requires API key*

**Oxylabs**

* Gather Data at Scale.
* *Requires API key*

### Communication & Messaging

**Sinch**

* Omnichannel messaging platform for SMS, WhatsApp, RCS, and other channels.
* *Requires API key*

### Brand & Asset Management

**Frontify**

* Brand management software.
* *Requires API key*

<Note>
  **Want to build a connector?** Join our [Discord community](https://discord.gg/PBYd6FbBSK) to collaborate on new integrations! We're expanding with more sports data providers, Zapier, CRM integrations, and more. Your expertise can help shape the future of fan experiences.
</Note>

## Using Connectors in Workflows

Connectors are used in workflows to fetch data or invoke AI services:

```yaml theme={null}
# Example: Fetching F1 data
- type: "connector"
  name: "task-load-f1-data"
  connector:
    name: "fastf1"
    command: "get_session_data"
  inputs:
    year: "$.get('year')"
    race: "$.get('race')"
    session: "$.get('session')"
  outputs:
    session_data: "$"

# Example: Invoking an AI model with OpenAI
- type: "prompt"
  name: "chat-completions-prompt"
  connector:
    name: "openai"
    command: "invoke_prompt"
    model: "gpt-4o"
  inputs:
    documents: "$.get('documents')"
    messages: "$.get('messages')"
  outputs:
    message: "$.get('choices')[0].get('message').get('content')"

# Example: Generating an image with Stability AI
- type: "connector"
  name: "generate-team-image"
  connector:
    name: "stability"
    command: "generate_image"
  inputs:
    params:
      image_id: "$.get('image_id')"
      configuration:
        prompt: "$.get('image_prompt')"
  outputs:
    generated_image: "$.get('data')"

# Example: Using document processing with Docling
- type: "connector"
  name: "process-documents"
  connector:
    name: "docling"
    command: "load_documents"
  inputs:
    file_path: "$.get('document_path')"
  outputs:
    parsed_content: "$"

# Example: Performing web search with Perplexity
- type: "connector"
  name: "web-search"
  connector:
    name: "perplexity"
    command: "query"
  inputs:
    query: "$.get('search_query')"
  outputs:
    search_results: "$"

# Example: Sending SMS with Sinch
- type: "connector"
  name: "send-customer-notification"
  connector:
    name: "sinch"
    command: "send_sms"
  inputs:
    to: "$.get('customer_phone')"
    from: "$.get('sender_id')"
    message: "$.get('notification_message')"
  outputs:
    message_id: "$.get('message_id')"
    status: "$.get('status')"

# Example: Sending WhatsApp template message with Sinch
- type: "connector"
  name: "send-whatsapp-notification"
  connector:
    name: "sinch"
    command: "send_whatsapp"
  inputs:
    to: "$.get('customer_phone')"
    template_id: "$.get('template_id')"
    parameters:
      - name: "customer_name"
        value: "$.get('customer_name')"
      - name: "order_number"
        value: "$.get('order_number')"
  outputs:
    message_id: "$.get('message_id')"
    status: "$.get('status')"

# Example: Sending omnichannel message with Sinch
- type: "connector"
  name: "send-omnichannel-message"
  connector:
    name: "sinch"
    command: "send_message"
  inputs:
    app_id: "$.get('sinch_app_id')"
    recipient:
      identified_by:
        channel_identities:
          - channel: "WHATSAPP"
            identity: "$.get('customer_phone')"
    message:
      text_message:
        text: "$.get('message_text')"
    channel_priority_order:
      - "WHATSAPP"
      - "SMS"
  outputs:
    message_id: "$.get('message_id')"

# Example: Fetching MLB standings data
- type: "connector"
  name: "get-mlb-standings"
  connector:
    name: "mlb-statsapi"
    command: "sync-standings"
  outputs:
    standings_data: "$.get('standings')"
```

## Setting Up Connectors

To use a connector in your project, follow these steps:

### 1. Configure Environment Variables

For connectors that require API keys, set up the necessary environment variables in your project:

```yaml theme={null}
context-variables:
  openai:
    api_key: "$TEMP_CONTEXT_VARIABLE_OPENAI_API_KEY"
  # Add other required API keys
```

### 2. Import the Connector

Add the connector to your workflow configuration:

```yaml theme={null}
connectors:
  - name: "openai"
    version: "latest"
  - name: "fastf1"
    version: "latest"
  - name: "mlb-statsapi"
    version: "latest"
  # Add other connectors as needed
```

### 3. Use the Connector in Your Workflow

Reference the connector in your workflow steps as shown in the examples above.

## Creating Custom Connectors

You can create your own connectors to integrate with additional services. A custom connector requires:

### 1. Configuration File (YML)

Create a configuration file that defines your connector:

```yaml theme={null}
connector:
  name: "my-custom-connector"
  description: "Description of what your connector does"
  filename: "my_connector.py"  # or .json for REST API connectors
  filetype: "pyscript"  # or "restapi"
  commands:
    - name: "Human-readable command name"
      value: "function_name_in_code"
```

### 2. Implementation File

For Python-based connectors, create a Python file with your command functions:

```python theme={null}
def function_name_in_code(request_data):
    # Process inputs from request_data
    # Perform operations
    # Return results
    return {"status": True, "data": result}
```

For REST API connectors, create a JSON file that defines the API endpoints and parameters.

### 3. Installation File

Create an `_install.yml` file to specify how your connector should be installed:

```yaml theme={null}
datasets:
  - type: "connector"
    path: "my-custom-connector.yml"
```

## Document Operations

The OpenAI connector supports various document operations:

```yaml theme={null}
# Example: Vector search for similar documents
- type: "document"
  name: "load-similar-documents"
  config:
    action: "search"
    threshold-docs: 10
    search-vector: true
  connector:
    name: "openai"
    command: "invoke_embedding"
    model: "text-embedding-3-small"
  inputs:
    name: "'content-snippet'"
    search-query: "$.get('messages')"
  outputs:
    documents: "$.get('documents')"
```

## Connector Commands

Each connector supports specific commands that you can use in your workflows. Here's a detailed breakdown:

### Groq

High-performance AI inference with fast response times.

* `invoke_prompt`: Execute an AI prompt with high performance
  ```yaml theme={null}
  connector:
    name: "groq"
    command: "invoke_prompt"
  inputs:
    model: "llama3-70b-8192"  # or other available models
    messages: "$.get('messages')"
  ```

* `invoke_embedding`: Generate embeddings for text
  ```yaml theme={null}
  connector:
    name: "groq"
    command: "invoke_embedding"
  inputs:
    model: "embedding-001"
    text: "$.get('text')"
  ```

### OpenAI

Advanced language models with a wide range of capabilities.

* `invoke_prompt`: Execute an AI prompt
  ```yaml theme={null}
  connector:
    name: "openai"
    command: "invoke_prompt"
  inputs:
    model: "gpt-4o"  # or other available models
    messages: "$.get('messages')"
    temperature: 0.7  # optional
  ```

* `invoke_embedding`: Generate or search embeddings
  ```yaml theme={null}
  connector:
    name: "openai"
    command: "invoke_embedding"
  inputs:
    model: "text-embedding-3-small"
    text: "$.get('text')"
  ```

* `transcribe_audio_to_text`: Convert audio to text
  ```yaml theme={null}
  connector:
    name: "openai"
    command: "transcribe_audio_to_text"
  inputs:
    file_path: "$.get('audio_file_path')"
    model: "whisper-1"  # optional
  ```

### Stability AI

AI image generation based on text prompts.

* `generate_image`: Generate AI images based on text prompts
  ```yaml theme={null}
  connector:
    name: "stability"
    command: "generate_image"
  inputs:
    params:
      image_id: "unique-id-for-image"
      configuration:
        prompt: "A detailed description of the image you want to generate"
        # Additional parameters like style, dimensions, etc.
  ```

### FastF1

Open-source Formula 1 data provider with comprehensive race information.

* `get_session_data`: Fetch session data for a specific race
  ```yaml theme={null}
  connector:
    name: "fastf1"
    command: "get_session_data"
  inputs:
    year: 2023  # F1 season year
    race: "Monaco"  # Race name or round number
    session: "Q"  # "FP1", "FP2", "FP3", "Q", "R" for different sessions
  ```

* `get_driver_info`: Get information about F1 drivers
  ```yaml theme={null}
  connector:
    name: "fastf1"
    command: "get_driver_info"
  inputs:
    driver: "VER"  # Driver abbreviation
    year: 2023  # Optional, defaults to current season
  ```

* `get_team_info`, `get_race_schedule`, `get_lap_data`, and `get_race_results` follow similar patterns with appropriate parameters.

### MLB StatsAPI

Comprehensive MLB baseball data API with endpoints for teams, seasons, schedules, standings, and player/team statistics.

The MLB StatsAPI connector provides access to baseball data through various commands:

* `sync-teams`: Retrieve MLB team information
  ```yaml theme={null}
  connector:
    name: "mlb-statsapi"
    command: "sync-teams"
  outputs:
    teams: "$.get('teams')"
  ```

* `sync-seasons`: Get MLB season information
  ```yaml theme={null}
  connector:
    name: "mlb-statsapi"
    command: "sync-seasons"
  outputs:
    seasons: "$.get('seasons')"
  ```

* `sync-schedule`: Fetch MLB game schedules
  ```yaml theme={null}
  connector:
    name: "mlb-statsapi"
    command: "sync-schedule"
  outputs:
    schedule: "$.get('schedule')"
  ```

* `sync-standings`: Get current MLB standings
  ```yaml theme={null}
  connector:
    name: "mlb-statsapi"
    command: "sync-standings"
  outputs:
    standings: "$.get('standings')"
  ```

* `sync-stats`: Retrieve player and team statistics
  ```yaml theme={null}
  connector:
    name: "mlb-statsapi"
    command: "sync-stats"
  outputs:
    player_stats: "$.get('player_stats')"
    team_stats: "$.get('team_stats')"
  ```

### Sportradar

Comprehensive soccer data API with endpoints for competitions, seasons, schedules, standings, and probabilities.

The Sportradar connector provides access to soccer data through various endpoints:

* Competitions data
* Season information
* Match schedules
* Team standings
* Game probabilities

Example usage:

```yaml theme={null}
connector:
  name: "sportradar-soccer"
  command: "competitions"  # or other available endpoints
inputs:
  region: "international"  # or other regions
```

### Docling

Document processing, including advanced PDF parsing.

* `invoke_loader`: Initialize document loader
  ```yaml theme={null}
  connector:
    name: "docling"
    command: "invoke_loader"
  inputs:
    loader_type: "pdf"  # or other supported document types
  ```

* `load_documents`: Load and process documents
  ```yaml theme={null}
  connector:
    name: "docling"
    command: "load_documents"
  inputs:
    file_path: "path/to/document.pdf"
    # Additional processing parameters
  ```

### Perplexity

Real-time web search powered by AI.

REST API for AI-powered web search and information retrieval:

```yaml theme={null}
connector:
  name: "perplexity"
  command: "query"
inputs:
  query: "Your search query here"
  # Optional parameters like max_results, etc.
```

### TallySight

* No specific commands documented

### Frontify

* `get_brand_assets`: Retrieve brand assets and guidelines
* `get_brand_colors`: Fetch brand color palette
* `get_brand_logos`: Access brand logo variations

### HeyGen

* `generate_video`: Create AI avatar videos

### Twelve Labs

* No specific commands documented

### Sinch

Messaging, email, and voice communication platform for customer engagement.

* `send_sms`: Send SMS messages to customers
  ```yaml theme={null}
  connector:
    name: "sinch"
    command: "send_sms"
  inputs:
    to: "+1234567890"  # Recipient phone number
    from: "+0987654321"  # Sender phone number or alphanumeric ID
    message: "Your message content here"
  ```

* `send_whatsapp`: Send WhatsApp messages
  ```yaml theme={null}
  connector:
    name: "sinch"
    command: "send_whatsapp"
  inputs:
    to: "+1234567890"  # Recipient phone number
    template_id: "your_template_id"  # WhatsApp template ID
    parameters:
      - name: "parameter_name"
        value: "parameter_value"
  ```

* `send_email`: Send email messages
  ```yaml theme={null}
  connector:
    name: "sinch"
    command: "send_email"
  inputs:
    to: "recipient@example.com"
    from: "sender@yourdomain.com"
    subject: "Email subject"
    body: "Email body content"
    html: true  # Optional, set to true for HTML content
  ```

* `send_voice`: Initiate voice calls
  ```yaml theme={null}
  connector:
    name: "sinch"
    command: "send_voice"
  inputs:
    to: "+1234567890"  # Recipient phone number
    from: "+0987654321"  # Caller phone number
    text: "Text to be spoken during the call"
    language: "en-US"  # Optional, language code
  ```

* `send_message`: Send messages across multiple channels (SMS, WhatsApp, RCS, Messenger, etc.)
  ```yaml theme={null}
  connector:
    name: "sinch"
    command: "send_message"
  inputs:
    app_id: "your_sinch_app_id"
    recipient:
      contact_id: "contact_id"  # Or use channel_identities for specific channels
    message:
      text_message:
        text: "Your message content here"
    channel_priority_order:  # Optional, specify channel preference
      - "WHATSAPP"
      - "SMS"
  ```

* `verify_number`: Verify phone numbers via SMS or voice
  ```yaml theme={null}
  connector:
    name: "sinch"
    command: "verify_number"
  inputs:
    phone_number: "+1234567890"
    method: "sms"  # or "voice"
  ```

## Environment Variables

Connectors use environment variables for API keys:

```yaml theme={null}
context-variables:
  sportradar-soccer:
    api_key: "$TEMP_CONTEXT_VARIABLE_SPORTRADAR_API_KEY"
  openai:
    api_key: "$TEMP_CONTEXT_VARIABLE_OPENAI_API_KEY"
  groq:
    api_key: "$TEMP_CONTEXT_VARIABLE_GROQ_API_KEY"
  perplexity:
    api_key: "$TEMP_CONTEXT_VARIABLE_PERPLEXITY_API_KEY"
  stability:
    api_key: "$TEMP_CONTEXT_VARIABLE_STABILITY_API_KEY"
  # Other connectors that require API keys
  bwin:
    api_key: "$TEMP_CONTEXT_VARIABLE_BWIN_API_KEY"
  frontify:
    api_key: "$TEMP_CONTEXT_VARIABLE_FRONTIFY_API_KEY"
  heygen:
    api_key: "$TEMP_CONTEXT_VARIABLE_HEYGEN_API_KEY"
  elevenlabs:
    api_key: "$TEMP_CONTEXT_VARIABLE_ELEVENLABS_API_KEY"
  twelvelabs:
    api_key: "$TEMP_CONTEXT_VARIABLE_TWELVELABS_API_KEY"
  tallysight:
    api_key: "$TEMP_CONTEXT_VARIABLE_TALLYSIGHT_API_KEY"
  sinch:
    api_key: "$TEMP_CONTEXT_VARIABLE_SINCH_API_KEY"
    api_secret: "$TEMP_CONTEXT_VARIABLE_SINCH_API_SECRET"
```

## Best Practices

When working with connectors, follow these best practices to ensure optimal performance and reliability:

### Error Handling

Implement robust error handling for API failures:

```yaml theme={null}
- type: "connector"
  name: "api-call"
  connector:
    name: "some-api"
    command: "some-command"
  inputs:
    param: "value"
  outputs:
    result: "$"
  on_failure:
    action: "retry"  # or "continue", "fail"
    max_retries: 3
    retry_delay: 1000  # milliseconds
```

### Caching

Cache frequently accessed data to improve performance and reduce API calls:

```yaml theme={null}
- type: "connector"
  name: "cached-api-call"
  config:
    cache:
      enabled: true
      ttl: 3600  # seconds (1 hour)
  connector:
    name: "some-api"
    command: "some-command"
  # Rest of the configuration
```

### Data Transformation

Use mappings to transform connector responses into a consistent format:

```yaml theme={null}
- type: "connector"
  name: "transform-data"
  connector:
    name: "some-api"
    command: "some-command"
  outputs:
    raw_data: "$"
  mappings:
    - source: "$.get('raw_data')"
      target: "transformed_data"
      transform: |
        function(data) {
          // Transform data here
          return transformedData;
        }
```

### Model Selection

Select the appropriate AI model based on your performance and cost requirements:

* Use `gpt-4o` or `llama3-70b` for complex reasoning tasks
* Use `gpt-3.5-turbo` or smaller models for simpler tasks
* Use specialized models for specific tasks (e.g., `whisper-1` for audio transcription)

### Rate Limiting

Monitor API usage to stay within rate limits:

```yaml theme={null}
- type: "connector"
  name: "rate-limited-call"
  config:
    rate_limit:
      requests_per_minute: 60
  connector:
    name: "some-api"
    command: "some-command"
  # Rest of the configuration
```

### Testing

Test your connector integrations thoroughly:

1. Create test workflows that exercise each connector
2. Test with sample data before using in production
3. Implement monitoring to track connector performance and errors

## Troubleshooting

Common issues and solutions when working with connectors:

### API Key Issues

If you encounter authentication errors:

* Verify that your API key is correctly set in the environment variables
* Check that the API key has the necessary permissions
* Ensure the API key is valid and not expired

### Rate Limiting

If you hit rate limits:

* Implement backoff strategies in your workflows
* Cache results where possible
* Consider upgrading your API plan if available

### Data Format Issues

If you encounter data parsing errors:

* Check the connector documentation for expected input formats
* Use mappings to transform data into the expected format
* Log and inspect the raw response data for debugging

## Next Steps

* Explore [Workflows](/core-components/workflows) to see how connectors are used in data processing
* Learn about [Mappings](/core-components/mappings) to transform data from connectors
* Review [Agents](/core-components/agents) to understand how connectors power scheduled tasks
* Join our [Discord community](https://discord.gg/PBYd6FbBSK) to collaborate on new connector integrations