Connectors

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

Python-based connectors (pyscript): Implemented as Python modules with defined functions
REST API connectors (restapi): Configured using JSON specifications for API endpoints
GraphQL connectors (graphql): Configured against a GraphQL schema

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

Around 50 connectors ship with the platform. The marketplace in Studio (Integrations → Connect a tool) is the live list — it's generated from what's actually installed across pods, so it's always ahead of this page. Below is the catalog grouped by what each one is for.

No credential needed means the connector works as soon as it's installed. Everything else needs an API key you supply once, stored in your project's Vault.

Language & multimodal models

Connector	What it's for	Credential
`google-genai`	Google Gemini models on Vertex AI — the platform default for prompts and embeddings.	Required
`vertex-embedding`	Vertex AI text embeddings (`text-embedding-004`).	Not needed
`groq`	High-performance inference for Llama and similar open models.	Required
`machina-ai`, `machina-ai-fast`	The platform's own model facades.	Varies
`azure-foundry`	Azure AI Foundry / Azure OpenAI.	Required
`grok`	xAI Grok chat completions.	Required
`nvidia-nim`	NVIDIA NIM chat (OpenAI-compatible), with a model allowlist.	Required
`google-speech-to-text`	Google Cloud Speech-to-Text.	Required

Sports data

Connector	What it's for	Credential
`sportradar-{mlb,nba,nfl,nhl,soccer,soccer-extended,tennis,rugby}`	Sportradar, one connector per sport — there is no single `sportradar` connector.	Required (rugby: not needed)
`opta`	Opta sports data.	Required
`api-football`, `american-football`	API-Football feeds.	Required
`goalserve-soccer-pyscript`	Goalserve soccer feed.	Required
`mlb-statsapi`	MLB Stats API — teams, seasons, schedules, standings, stats.	Not needed
`fastf1`	Open-source Formula 1 data.	Not needed
`sports-skills`	Aggregator over the open-source Sports Skills domains.	Not needed
`coverage-get-current-season`, `sportradar-nfl-detect-season-type`	Small helpers for resolving the current season/season type.	Not needed

Betting, odds & prediction markets

Connector	What it's for	Credential
`bwin`	bwin Sports API — fixtures, competitions, odds, live scoreboards.	Required
`bwin-grep-sports`, `bwin-odds-delta`	Filter bwin markets; track odds deltas over time.	Not needed
`tallysight`	Betting widgets, odds, and market data.	Required
`polymarket`	Polymarket prediction markets — events, markets, prices.	Not needed
`kalshi`	Kalshi prediction markets — events, markets, trading data.	Not needed

Media generation

Connector	What it's for	Credential
`stability`	AI image generation.	Not needed
`elevenlabs`	Lifelike spoken audio.	Required
`byteplus-modelark`	Async text-to-video generation.	Required

Search & content retrieval

Connector	What it's for	Credential
`perplexity`	Real-time web search powered by AI.	Required
`exa-search`	Internet-scale semantic search.	Required
`oxylabs`	Data gathering at scale.	Required
`rss-feed`	Fetch and parse RSS/Atom feeds.	Not needed
`sociavault`	Social media data (Instagram profiles, posts, reels).	Required
`docling`	Document processing, including advanced PDF parsing.	Not needed
`temp-downloader`	Download a file to temp storage and read it.	Not needed

Delivery, storage & workplace tools

Connector	What it's for	Credential
`slack-webhook`	Post to Slack via Incoming Webhooks.	Required
`resend`	Transactional email.	Required
`wordpress`	WordPress REST API — publish generated content.	Required
`zendesk`	Zendesk Help Center articles and content.	Required
`google-storage`, `storage`	Upload and serve files from object storage.	Varies
`mongodb-atlas`	Shared document cache with TTL support.	Not needed

TIP

Want to build a connector? Join our Discord community to collaborate on new integrations! 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:

yaml

# 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 Google Gemini
- type: "prompt"
  name: "chat-completions-prompt"
  connector:
    name: "google-genai"
    command: "invoke_prompt"
    model: "gemini-2.5-pro"
    location: "global"
    provider: "vertex_ai"
  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: Fetching MLB standings data
- type: "connector"
  name: "get-mlb-standings"
  connector:
    name: "mlb-statsapi"
    command: "get-v1-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

context-variables:
  google-genai:
    api_key: "$TEMP_CONTEXT_VARIABLE_GOOGLE_GENERATIVE_AI_API_KEY"
  # Add other required API keys

2. Import the Connector

Add the connector to your workflow configuration:

yaml

connectors:
  - name: "google-genai"
    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

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

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

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

Document Operations

The google-genai connector supports various document operations:

yaml

# Example: Vector search for similar documents
- type: "document"
  name: "load-similar-documents"
  config:
    action: "search"
    threshold-docs: 10
    search-vector: true
  connector:
    name: "google-genai"
    command: "invoke_embedding"
    model: "text-embedding-004"
    location: "global"
    provider: "vertex_ai"
  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

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

connector:
  name: "groq"
  command: "invoke_embedding"
inputs:
  model: "embedding-001"
  text: "$.get('text')"

Google Gemini (`google-genai`)

Advanced language models with a wide range of capabilities, running on Vertex AI.

invoke_prompt: Execute an AI prompt

yaml

connector:
  name: "google-genai"
  command: "invoke_prompt"
  location: "global"
  provider: "vertex_ai"
inputs:
  model: "gemini-2.5-pro"  # or other available Gemini models
  messages: "$.get('messages')"

invoke_embedding: Generate or search embeddings

yaml

connector:
  name: "google-genai"
  command: "invoke_embedding"
  location: "global"
  provider: "vertex_ai"
inputs:
  model: "text-embedding-004"
  text: "$.get('text')"

transcribe_audio_to_text: Convert audio to text.

Stability AI

AI image generation based on text prompts.

generate_image: Generate AI images based on text prompts

yaml

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

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

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 (names below are the real, path-derived command strings — not the workflow file names, which are sync-teams.yml etc.):

get-v1-teams: Retrieve MLB team information

yaml

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

get-api/v1/seasons/{seasonId}: Get MLB season information

yaml

connector:
  name: "mlb-statsapi"
  command: "get-api/v1/seasons/{seasonId}"
  command_attribute:
    seasonId: "$.get('seasonId')"

get-v1-schedule: Fetch MLB game schedules

yaml

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

get-v1-standings: Get current MLB standings

yaml

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

get-v1-stats / get-v1-stats-leaders: Retrieve player and team statistics
yaml
```
connector:
  name: "mlb-statsapi"
  command: "get-v1-stats"
```

Sportradar

Sportradar is one connector per sport, not a single connector with a sport parameter — sportradar-soccer, sportradar-nba, sportradar-nfl, sportradar-mlb, sportradar-nhl, sportradar-tennis, sportradar-rugby, and sportradar-soccer-extended. Each wraps that sport's Sportradar API version, so its commands and credential are its own.

sportradar-soccer (API v4) covers competitions, seasons, schedules, standings, and probabilities:

yaml

connector:
  name: "sportradar-soccer"
  command: "competitions"  # or other available endpoints
inputs:
  region: "international"  # or other regions

Path-parameterized endpoints take their values through command_attribute:

yaml

connector:
  name: "sportradar-nba"
  command: "get-teams/{team_id}/{data_type}"
  command_attribute:
    team_id: "$.get('team_id')"
    data_type: "'profile.json'"

Docling

Document processing, including advanced PDF parsing.

invoke_loader: Initialize document loader

yaml

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

load_documents: Load and process documents

yaml

connector:
  name: "docling"
  command: "load_documents"
inputs:
  file_path: "path/to/document.pdf"
  # Additional processing parameters

Perplexity

Real-time web search powered by AI, via its /chat/completions REST endpoint. It accepts model (e.g. "sonar") and messages (the same role/content shape as a chat completion), plus optional max_tokens and temperature.

TallySight

No specific commands documented

Environment Variables

Connectors use environment variables for API keys:

yaml

context-variables:
  sportradar-soccer:
    api_key: "$TEMP_CONTEXT_VARIABLE_SPORTRADAR_SOCCER_V4_API_KEY"
  google-genai:
    api_key: "$TEMP_CONTEXT_VARIABLE_GOOGLE_GENERATIVE_AI_API_KEY"
  groq:
    api_key: "$TEMP_CONTEXT_VARIABLE_GROQ_API_KEY"
  perplexity:
    api_key: "$TEMP_CONTEXT_VARIABLE_PERPLEXITY_API_KEY"
  # Other connectors that require API keys
  bwin:
    access_id: "$TEMP_CONTEXT_VARIABLE_BWIN_ACCESS_ID"
    access_id_token: "$TEMP_CONTEXT_VARIABLE_BWIN_ACCESS_ID_TOKEN"
  elevenlabs:
    api_key: "$TEMP_CONTEXT_VARIABLE_ELEVENLABS_API_KEY"
  exa-search:
    api_key: "$TEMP_CONTEXT_VARIABLE_EXA_API_KEY"
  tallysight:
    api_key: "$TEMP_CONTEXT_VARIABLE_TALLYSIGHT_API_KEY"
  oxylabs:
    username: "$TEMP_CONTEXT_VARIABLE_OXYLABS_USERNAME"
    password: "$TEMP_CONTEXT_VARIABLE_OXYLABS_PASSWORD"
  slack-webhook:
    webhook_url: "$TEMP_CONTEXT_VARIABLE_SLACK_WEBHOOK_URL"
  resend:
    api_key: "$TEMP_CONTEXT_VARIABLE_RESEND_API_KEY"
  # Connectors marked "Not needed" in the catalog above (fastf1, mlb-statsapi,
  # docling, stability, polymarket, kalshi, rss-feed, …) declare no credential.

Studio fills these in for you when you paste a key into the connector marketplace — you only write this block by hand when authoring a template outside Studio. The authoritative per-connector variable names are the ones the marketplace shows for that connector.

Best Practices

Error handling — `continue_on_error`

A connector task that fails aborts the workflow by default. Set continue_on_error: true to let the run proceed and handle the empty result downstream — this is the only error-handling key a task supports:

yaml

- type: "connector"
  name: "load-odds"
  continue_on_error: true
  connector:
    name: "bwin"
    command: "get-fixtures"
  outputs:
    odds: "$"

# Downstream tasks guard on the result instead of assuming it's there
- type: "prompt"
  name: "summarize-odds"
  condition: "len($.get('odds', [])) > 0"
  # ...

There is no declarative retry or backoff. If a step must be retried, model it as a separate scheduled run: leave the document unwritten on failure and let the agent's next cadence pick it up (that's how the platform's own sync workflows behave).

Skipping work you've already done

There's no cache block either. Templates cache by writing results to a document and guarding the expensive task with a condition:

yaml

# 1. Try to load a previously stored result
- type: "document"
  name: "load-cached"
  config:
    action: "search"
    search-limit: 1
  inputs:
    name: "'odds-cache'"
  outputs:
    cached: "($.get('documents', [{}])[0]).get('value', {})"

# 2. Only call the API when there's nothing cached
- type: "connector"
  name: "load-odds"
  condition: "not $.get('cached')"
  connector:
    name: "bwin"
    command: "get-fixtures"
  outputs:
    odds: "$"

Freshness is your own condition to express — there's no TTL the platform enforces for you.

Transforming responses

Use a mapping task to reshape a connector response, not a key on the connector task. See Mappings for the full structure:

yaml

- type: "connector"
  name: "fetch-team-data"
  connector:
    name: "sportradar-nba"
    command: "get-teams/{team_id}/{data_type}"
    command_attribute:
      team_id: "$.get('team_id')"
      data_type: "'profile.json'"
  outputs:
    team-profile: "$"

- type: "mapping"
  name: "sportradar-nba-team-mapping"
  inputs:
    team_profile: "$.get('team-profile')"
  outputs:
    team_name: "$.get('team_name')"

Model selection

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

Use gemini-2.5-pro for complex reasoning tasks
Use smaller/faster models (e.g. gemini-2.5-flash, or llama-3.1-8b-instant via Groq) for simpler tasks
Use specialized models for specific tasks (e.g. text-embedding-004 for embeddings)

Rate limiting

Rate limits are enforced platform-side per task type — there is no per-task rate_limit key you can set in a workflow. If you're hitting a provider's limit, lower the triggering agent's cadence (config-frequency, see Configuring Agents) rather than trying to throttle inside the workflow.

Testing

Create test workflows that exercise each connector
Test with sample data before using in production
Watch a run with machina workflow run <name> --sync and inspect it with machina execution get <id>

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

Connectors ​

Connector Structure ​

Available Connectors ​

Language & multimodal models ​

Sports data ​

Betting, odds & prediction markets ​

Media generation ​

Search & content retrieval ​

Delivery, storage & workplace tools ​

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 ​

Google Gemini (google-genai) ​

Stability AI ​

FastF1 ​

MLB StatsAPI ​

Sportradar ​

Docling ​

Perplexity ​

TallySight ​

Environment Variables ​

Best Practices ​

Error handling — continue_on_error ​

Skipping work you've already done ​

Transforming responses ​

Model selection ​

Rate limiting ​

Testing ​

Troubleshooting ​

API Key Issues ​

Rate Limiting ​

Data Format Issues ​

Next Steps ​

Connectors

Connector Structure

Available Connectors

Language & multimodal models

Sports data

Betting, odds & prediction markets

Media generation

Search & content retrieval

Delivery, storage & workplace tools

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

Google Gemini (`google-genai`)

Stability AI

FastF1

MLB StatsAPI

Sportradar

Docling

Perplexity

TallySight

Environment Variables

Best Practices

Error handling — `continue_on_error`

Skipping work you've already done

Transforming responses

Model selection

Rate limiting

Testing

Troubleshooting

API Key Issues

Rate Limiting

Data Format Issues

Next Steps