Connectors - Machina Sports Docs

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:

A configuration file (.yml) that defines the connector’s name, description, and available commands
An implementation file (.py) for Python-based connectors or (.json) for REST API connectors
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

Each token from GPT Image 1 counts as 2x on token execution counts.

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

Want to build a connector? Join our Discord community 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.

Using Connectors in Workflows

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

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

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:

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:

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:

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:

datasets:
  - type: "connector"
    path: "my-custom-connector.yml"

Document Operations

The OpenAI connector supports various document operations:

# 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

connector:
  name: "groq"
  command: "invoke_prompt"
inputs:
  model: "llama3-70b-8192"  # or other available models
  messages: "$.get('messages')"

invoke_embedding: Generate embeddings for text

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

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

connector:
  name: "openai"
  command: "invoke_embedding"
inputs:
  model: "text-embedding-3-small"
  text: "$.get('text')"

transcribe_audio_to_text: Convert audio to text

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

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

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

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

connector:
  name: "mlb-statsapi"
  command: "sync-teams"
outputs:
  teams: "$.get('teams')"

sync-seasons: Get MLB season information

connector:
  name: "mlb-statsapi"
  command: "sync-seasons"
outputs:
  seasons: "$.get('seasons')"

sync-schedule: Fetch MLB game schedules

connector:
  name: "mlb-statsapi"
  command: "sync-schedule"
outputs:
  schedule: "$.get('schedule')"

sync-standings: Get current MLB standings

connector:
  name: "mlb-statsapi"
  command: "sync-standings"
outputs:
  standings: "$.get('standings')"

sync-stats: Retrieve player and team statistics

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:

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

connector:
  name: "docling"
  command: "invoke_loader"
inputs:
  loader_type: "pdf"  # or other supported document types

load_documents: Load and process documents

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:

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

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

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

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

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

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

connector:
  name: "sinch"
  command: "verify_number"
inputs:
  phone_number: "+1234567890"
  method: "sms"  # or "voice"

Environment Variables

Connectors use environment variables for API keys:

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:

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

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

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

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

Create test workflows that exercise each connector
Test with sample data before using in production
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 to see how connectors are used in data processing
Learn about Mappings to transform data from connectors
Review Agents to understand how connectors power scheduled tasks
Join our Discord community to collaborate on new connector integrations

​Connector Structure

​Available Connectors

​Language Models

​Sports Data

​Betting & Odds

​Media Generation

​Content Processing

​Web Search Retrieval

​Communication & Messaging

​Brand & Asset Management

​Using Connectors in Workflows

​Setting Up Connectors

​1. Configure Environment Variables

​2. Import the Connector

​3. Use the Connector in Your Workflow

​Creating Custom Connectors

​1. Configuration File (YML)

​2. Implementation File

​3. Installation File

​Document Operations

​Connector Commands

​Groq

​OpenAI

​Stability AI

​FastF1

​MLB StatsAPI

​Sportradar

​Docling

​Perplexity

​TallySight

​Frontify

​HeyGen

​Twelve Labs

​Sinch

​Environment Variables

​Best Practices

​Error Handling

​Caching

​Data Transformation

​Model Selection

​Rate Limiting

​Testing

​Troubleshooting

​API Key Issues

​Rate Limiting

​Data Format Issues

​Next Steps

Connector Structure

Available Connectors

Language Models

Sports Data

Betting & Odds

Media Generation

Content Processing

Web Search Retrieval

Communication & Messaging

Brand & Asset Management

Using Connectors in Workflows

Setting Up Connectors

1. Configure Environment Variables

2. Import the Connector

3. Use the Connector in Your Workflow

Creating Custom Connectors

1. Configuration File (YML)

2. Implementation File

3. Installation File

Document Operations

Connector Commands

Groq

OpenAI

Stability AI

FastF1

MLB StatsAPI

Sportradar

Docling

Perplexity

TallySight

Frontify

HeyGen

Twelve Labs

Sinch

Environment Variables

Best Practices

Error Handling

Caching

Data Transformation

Model Selection

Rate Limiting

Testing

Troubleshooting

API Key Issues

Rate Limiting

Data Format Issues

Next Steps