> ## Documentation Index > Fetch the complete documentation index at: https://docs.maia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a new Runner > Creates a new Runner 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. ## OpenAPI ````yaml /openapi/public-api-endpoint-reference.yaml post /v1/agents openapi: 3.1.0 info: title: Maia Public REST API version: '1.0' servers: - description: EU1 url: https://eu1.api.matillion.com/dpc - description: US1 url: https://us1.api.matillion.com/dpc - description: AU1 url: https://au1.api.matillion.com/dpc security: - bearerAuth: [] tags: - description: Manage Schedules name: Schedules - description: Manage Connections name: Connections - description: Operations for managing Project Variables name: Project Variables - description: Manage Pipelines name: Pipelines - description: Review pipelines against quality rules name: Pipeline Quality Review - description: >- Describe how to configure a connection for a given auth provider, auth type and platform connection type. name: Connection Schema - description: Execute tests within a project name: Test Execution - description: Manage your AI agent tasks name: AI Agent Tasks - description: SCIM endpoints for user/group permission management name: Directory Integration - description: Publish shared pipeline artifacts name: Shared Pipeline Artifacts - description: Manage Repositories name: Repositories - description: Report on Credit Consumption name: Consumption - description: >- Start and track the migration of a Git repository into a project's working tree. name: Repository Migration - description: Manage Artifacts name: Artifacts - description: Operations for data lineage and governance name: Data Lineage - description: Manage Runners name: Runners - description: Manage Streaming Pipelines name: Streaming Pipelines - description: Execute a pipeline name: Pipeline Execution - description: '' name: Environments - description: '' name: Projects - description: Operations for managing Environment-level Overrides of Project Variables name: Project Variable Environment Overrides - description: Query audit events name: Audit Events - description: Connector Profiles name: Connectors paths: /v1/agents: post: tags: - Runners summary: Create a new Runner description: >- Creates a new Runner 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. operationId: createAgent requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/AgentInfo' description: Runner created successfully '400': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' example: type: https://api.matillion.com/problems/bad-request title: Bad Request status: 400 detail: Failed to read request. Please check your request body. instance: /v1/agents description: Invalid request body used '403': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' example: type: https://api.matillion.com/problems/forbidden title: Forbidden status: 403 detail: You do not have permission to access this resource. instance: /v1/agents description: Forbidden '500': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' example: type: https://api.matillion.com/problems/internal-server-error title: Internal Server Error status: 500 detail: Unexpected error occurred while processing the request. instance: /v1/agents description: Unexpected error occurred components: schemas: CreateAgentRequest: type: object properties: agentType: type: string description: The type of Runner being created enum: - data_productivity_cloud - streaming example: data_productivity_cloud minLength: 1 cloudProvider: type: string description: >- The cloud provider of the Runner to be created. The Cloud Provider must correspond with the chosen Runner Type. Available cloud providers are: - aws - Available for both data_productivity_cloud and streaming Runner Types. - azure - Available for both data_productivity_cloud and streaming Runner Types. - snowflake - Only available for data_productivity_cloud Runner Types. - gcp - Available for both data_productivity_cloud and streaming Runner Types. - google_cloud - Alias for gcp, available for both data_productivity_cloud and streaming Runner Types. - maia - Only available for data_productivity_cloud Runner Types. Creates a Maia-hosted runner managed by Matillion. enum: - aws - azure - snowflake - google_cloud - gcp - maia example: aws minLength: 1 deployment: type: string description: >- The deployment type of the Runner to be created. The Deployment Type must correspond with the chosen Runner Type and Cloud Provider. Available deployment types are: - fargate - Available for AWS Cloud Provider, for both data_productivity_cloud and streaming Runner Types. - eks - Available for AWS Cloud provider, for both data_productivity_cloud and streaming Runner Types. - container app - Available for Azure Cloud provider, only for data_productivity_cloud Runner Types. - aci - Available for Azure Cloud provider, only for streaming Runner Types. - aks - Available for Azure Cloud provider, for both data_productivity_cloud and streaming Runner Types. - native app - Available for Snowflake Cloud provider, only for data_productivity_cloud Runner Types. - gke - Available for Google Cloud provider, for both data_productivity_cloud and streaming Runner Types. - gce - Available for Google Cloud provider, only for streaming Runner Types. - custom_k8s - Only available for Maia cloud provider, only for data_productivity_cloud Runner Types. enum: - fargate - eks - container app - aks - aci - native app - gke - gce - custom_k8s example: fargate minLength: 1 description: type: string description: The description to set for the Runner being created example: An AWS Runner maxLength: 500 minLength: 0 enableAutoUpdates: type: boolean description: >- Whether the Runner being created is set to automatically update. Note, this is not available for Snowflake Runners or Streaming Runners. example: true name: type: string description: The name to set for the Runner being created example: AWS Runner maxLength: 30 minLength: 1 restrictedAccess: type: boolean description: >- Whether the Runner is restricted to a specific set of projects. If set to true, the Runner will only be applicable to projects it is scoped to have access to. Note, this cannot be set for Streaming Runners. example: true trackName: type: string description: >- The version track applied to the Runner being created. This is not required for Streaming Runners. Note, Snowflake Runners can only be on the STABLE track. enum: - current - stable example: current required: - agentType - cloudProvider - deployment - name AgentInfo: type: object properties: agentId: type: string description: The ID of the Runner example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 agentStatus: type: string description: The reported status of the Runner example: running agentType: type: string description: The type of Runner example: data_productivity_cloud cloudProvider: type: string description: The cloud provider the Runner is hosted in example: aws connected: type: boolean description: Whether the Runner is connected example: true deployment: type: string description: The deployment type of the Runner example: fargate description: type: string description: The description set for the Runner example: An AWS Runner enableAutoUpdates: type: boolean description: Whether the Runner is set to automatically update example: true name: type: string description: The name of the Runner example: AWS Runner pausedUntil: type: string description: >- The date and time the Runner will be unpaused automatically. Only returned if the Runner is currently paused example: '2025-01-01T00:00:00.000Z' restrictedAccess: type: boolean description: Whether the Runner is restricted to a specific set of projects example: true versionDetails: $ref: '#/components/schemas/VersionDetails' description: The version details of the Runner ProblemDetail: type: object properties: detail: type: string instance: type: string status: type: integer format: int32 title: type: string type: type: string format: uri violations: type: array items: type: string VersionDetails: type: object properties: agentUpdateAvailable: type: boolean description: Whether an update is available for the runner example: false agentVersion: type: string description: The reported version of the runner example: 1.0.0 support: type: string description: Whether the runner is supported or unsupported enum: - SUPPORTED - UNSUPPORTED example: SUPPORTED trackName: type: string description: The name of the version track the Runner is on example: current trackReleaseDate: type: string description: The date the latest version of the version track was released example: '2025-01-01T00:00:00.000Z' trackVersion: type: string description: The latest version of the version track the runner is on example: 1.0.0 securitySchemes: bearerAuth: bearerFormat: JWT description: a valid bearer token scheme: bearer type: http ````