Sign in

v1

latestOpenAPI 3.1.02026-07-22106199311.5 KB
Agents

Create a new Agent

Creates a new Agent with the specified configuration details.

Please note that some combinations are not compatible, for example, an agentType of 'streaming' cannot have the enableAutoUpdates set to true.

post/v1/agents

Request body

agentType'data_productivity_cloud' | 'streaming' required

The type of Agent being created

cloudProvider'aws' | 'azure' | 'snowflake' | 'google_cloud' | 'gcp' | 'maia' required

The cloud provider of the Agent to be created. The Cloud Provider must correspond with the chosen Agent Type.

Available cloud providers are:

  • aws - Available for both data_productivity_cloud and streaming Agent Types.
  • azure - Available for both data_productivity_cloud and streaming Agent Types.
  • snowflake - Only available for data_productivity_cloud Agent Types.
  • gcp - Available for both data_productivity_cloud and streaming Agent Types.
  • google_cloud - Alias for gcp, available for both data_productivity_cloud and streaming Agent Types.
  • maia - Only available for data_productivity_cloud Agent Types. Creates a Maia-hosted runner managed by Matillion.
deployment'fargate' | 'eks' | 'container app' | 'aks' | 'aci' | 'native app' | 'gke' | 'gce' | 'custom_k8s' required

The deployment type of the Agent to be created. The Deployment Type must correspond with the chosen Agent Type and Cloud Provider.

Available deployment types are:

  • fargate - Available for AWS Cloud Provider, for both data_productivity_cloud and streaming Agent Types.
  • eks - Available for AWS Cloud provider, for both data_productivity_cloud and streaming Agent Types.
  • container app - Available for Azure Cloud provider, only for data_productivity_cloud Agent Types.
  • aci - Available for Azure Cloud provider, only for streaming Agent Types.
  • aks - Available for Azure Cloud provider, for both data_productivity_cloud and streaming Agent Types.
  • native app - Available for Snowflake Cloud provider, only for data_productivity_cloud Agent Types.
  • gke - Available for GCP Cloud provider, for both data_productivity_cloud and streaming Agent Types.
  • gce - Available for GCP Cloud provider, only for streaming Agent Types.
  • custom_k8s - Only available for Maia cloud provider, only for data_productivity_cloud Agent Types.
descriptionstring

The description to set for the Agent being created

enableAutoUpdatesboolean

Whether the Agent being created is set to automatically update.

Note, this is not available for Snowflake Agents or Streaming Agents.

namestring required

The name to set for the Agent being created

restrictedAccessboolean

Whether the Agent is restricted to a specific set of projects. If set to true, the Agent will only be applicable to projects it is scoped to have access to.

Note, this cannot be set for Streaming Agents.

trackName'current' | 'stable'

The version track applied to the Agent being created. This is not required for Streaming Agents.

Note, Snowflake Agents can only be on the STABLE track.

Example request

{
  "agentType": "data_productivity_cloud",
  "cloudProvider": "aws",
  "deployment": "fargate",
  "description": "An AWS Agent",
  "enableAutoUpdates": true,
  "name": "AWS Agent",
  "restrictedAccess": true,
  "trackName": "current"
}

Response

Agent created successfully

agentIdstring

The ID of the Agent

agentStatusstring

The reported status of the Agent

agentTypestring

The type of Agent

cloudProviderstring

The cloud provider the Agent is hosted in

connectedboolean

Whether the Agent is connected

deploymentstring

The deployment type of the Agent

descriptionstring

The description set for the Agent

enableAutoUpdatesboolean

Whether the Agent is set to automatically update

namestring

The name of the Agent

pausedUntilstring

The date and time the Agent will be unpaused automatically. Only returned if the Agent is currently paused

restrictedAccessboolean

Whether the Agent is restricted to a specific set of projects

Example response

{
  "agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agentStatus": "running",
  "agentType": "data_productivity_cloud",
  "cloudProvider": "aws",
  "connected": true,
  "deployment": "fargate",
  "description": "An AWS Agent",
  "enableAutoUpdates": true,
  "name": "AWS Agent",
  "pausedUntil": "2025-01-01T00:00:00.000Z",
  "restrictedAccess": true,
  "versionDetails": {
    "agentVersion": "1.0.0",
    "support": "SUPPORTED",
    "trackName": "current",
    "trackReleaseDate": "2025-01-01T00:00:00.000Z",
    "trackVersion": "1.0.0"
  }
}