---
title: "Create an API connector"
method: POST
path: "/v2/api-connectors"
tags: ["API connectors"]
---

# Create an API connector

`POST /v2/api-connectors`

## Request

- Base URL: `https://api.sigmacomputing.com`
- URL: `https://api.sigmacomputing.com/v2/api-connectors`
- Auth: HTTP bearer

This endpoint creates a new API connector that defines how to call an external HTTP endpoint from within Sigma. For more information on API connectors, see [Configure API credentials and connectors in Sigma](https://help.sigmacomputing.com/docs/configure-api-credentials-and-connectors-in-sigma).

### Usage notes
- The user making this request must be assigned an account type with the **Manage API connectors** permission enabled.
- If a credential is provided using the `authId` parameter, the user making this request must have at least **Can view** permission on the credential and the request URL must match the credential's allowlist.
- Retrieve the **apiCredentialId** (used as `authId`) by calling the [/v2/api-credentials](https://help.sigmacomputing.com/reference/list-api-credentials) endpoint.

### Usage scenarios
- **Programmatic connector setup:** Automate creation of API connectors as part of an environment provisioning workflow.
- **Integration onboarding:** Create connectors for each external service your workbooks need to interact with.

## Request body

- object
  - `name` string, required: Display name of the connector.
  - `params` V2ApiConnectorsPostRequestBodyContentApplicationJsonSchemaParams, required
    - `method` 'GET' | 'POST' | 'DELETE' | 'PATCH' | 'PUT' | 'OPTIONS' | 'HEAD', required: HTTP method to invoke.
    - `url` string, required: Request URL. Must resolve to a hostname matching the associated credential's allowlist.
    - `headers` V2ApiConnectorsPostRequestBodyContentApplicationJsonSchemaParamsHeadersItems[], required: Static or dynamic request headers.
      - `key` string, required
      - `mode` 'static' | 'dynamic', required
      - `value` string, nullable
      - `type` 'array' | 'boolean' | 'number' | 'object' | 'raw' | 'string'
      - `shape` union
        - ParamShapeNode0
          - `type` ParamShapeNodeOneOf0TypeItems[], required
        - ParamShapeNode1
          - `type` ParamShapeNodeOneOf1TypeItems[], required
        - ParamShapeNode2
          - `type` ParamShapeNodeOneOf2TypeItems[], required
        - ParamShapeNode3
          - `type` ParamShapeNodeOneOf3TypeItems[], required
          - `properties` object, required
        - ParamShapeNode4
          - `type` ParamShapeNodeOneOf4TypeItems[], required
          - `items` ParamShapeNode, required (recursive)
        - object
    - `pathParams` V2ApiConnectorsPostRequestBodyContentApplicationJsonSchemaParamsPathParamsItems[], required: Path parameter placeholders resolved into the URL.
      - `key` string, required
      - `mode` 'static' | 'dynamic', required
      - `value` string, nullable
      - `type` 'array' | 'boolean' | 'number' | 'object' | 'raw' | 'string'
      - `shape` union
        - ParamShapeNode0
          - `type` ParamShapeNodeOneOf0TypeItems[], required
        - ParamShapeNode1
          - `type` ParamShapeNodeOneOf1TypeItems[], required
        - ParamShapeNode2
          - `type` ParamShapeNodeOneOf2TypeItems[], required
        - ParamShapeNode3
          - `type` ParamShapeNodeOneOf3TypeItems[], required
          - `properties` object, required
        - ParamShapeNode4
          - `type` ParamShapeNodeOneOf4TypeItems[], required
          - `items` ParamShapeNode, required (recursive)
        - object
    - `queryParams` V2ApiConnectorsPostRequestBodyContentApplicationJsonSchemaParamsQueryParamsItems[], required: Query string parameters.
      - `key` string, required
      - `mode` 'static' | 'dynamic', required
      - `value` string, nullable
      - `type` 'array' | 'boolean' | 'number' | 'object' | 'raw' | 'string'
      - `shape` union
        - ParamShapeNode0
          - `type` ParamShapeNodeOneOf0TypeItems[], required
        - ParamShapeNode1
          - `type` ParamShapeNodeOneOf1TypeItems[], required
        - ParamShapeNode2
          - `type` ParamShapeNodeOneOf2TypeItems[], required
        - ParamShapeNode3
          - `type` ParamShapeNodeOneOf3TypeItems[], required
          - `properties` object, required
        - ParamShapeNode4
          - `type` ParamShapeNodeOneOf4TypeItems[], required
          - `items` ParamShapeNode, required (recursive)
        - object
    - `body` string, required: Raw request body template.
  - `description` string: Human-readable description.
  - `config` V2ApiConnectorsPostRequestBodyContentApplicationJsonSchemaConfig
    - `timeout` V2ApiConnectorsPostRequestBodyContentApplicationJsonSchemaConfigTimeout: Per-request timeout configuration.
      - `requestSec` number, double, required
    - `retry` V2ApiConnectorsPostRequestBodyContentApplicationJsonSchemaConfigRetry: Retry policy. `retryableStatusCodes` are HTTP codes that should trigger a retry.
      - `maxRetries` number, double, required
      - `retryableStatusCodes` number[], required
    - `redirects` V2ApiConnectorsPostRequestBodyContentApplicationJsonSchemaConfigRedirects: HTTP redirect handling.
      - `maxRedirects` number, double, required
    - `rateLimit` V2ApiConnectorsPostRequestBodyContentApplicationJsonSchemaConfigRateLimit: Rate limit applied to outbound requests from this connector.
      - `maxRequestsPerWindow` number, double, required
  - `authId` string: Identifier of the API credential (`apiCredentialId`) used to authenticate requests.

## Response `200`

The response body.

- ApiConnectorsCreateApiConnectorResponse200
  - `apiConnectorId` string, required: Unique identifier of the API connector.
  - `name` string, required: Display name of the connector.
  - `params` V2ApiConnectorsPostResponsesContentApplicationJsonSchemaParams, required
    - `method` 'GET' | 'POST' | 'DELETE' | 'PATCH' | 'PUT' | 'OPTIONS' | 'HEAD', required: HTTP method to invoke.
    - `url` string, required: Request URL. Must resolve to a hostname matching the associated credential's allowlist.
    - `headers` V2ApiConnectorsPostResponsesContentApplicationJsonSchemaParamsHeadersItems[], required: Static or dynamic request headers.
      - `key` string, required
      - `mode` 'static' | 'dynamic', required
      - `value` string, nullable
      - `type` 'array' | 'boolean' | 'number' | 'object' | 'raw' | 'string'
      - `shape` union
        - ParamShapeNode0
          - `type` ParamShapeNodeOneOf0TypeItems[], required
        - ParamShapeNode1
          - `type` ParamShapeNodeOneOf1TypeItems[], required
        - ParamShapeNode2
          - `type` ParamShapeNodeOneOf2TypeItems[], required
        - ParamShapeNode3
          - `type` ParamShapeNodeOneOf3TypeItems[], required
          - `properties` object, required
        - ParamShapeNode4
          - `type` ParamShapeNodeOneOf4TypeItems[], required
          - `items` ParamShapeNode, required (recursive)
        - object
    - `pathParams` V2ApiConnectorsPostResponsesContentApplicationJsonSchemaParamsPathParamsItems[], required: Path parameter placeholders resolved into the URL.
      - `key` string, required
      - `mode` 'static' | 'dynamic', required
      - `value` string, nullable
      - `type` 'array' | 'boolean' | 'number' | 'object' | 'raw' | 'string'
      - `shape` union
        - ParamShapeNode0
          - `type` ParamShapeNodeOneOf0TypeItems[], required
        - ParamShapeNode1
          - `type` ParamShapeNodeOneOf1TypeItems[], required
        - ParamShapeNode2
          - `type` ParamShapeNodeOneOf2TypeItems[], required
        - ParamShapeNode3
          - `type` ParamShapeNodeOneOf3TypeItems[], required
          - `properties` object, required
        - ParamShapeNode4
          - `type` ParamShapeNodeOneOf4TypeItems[], required
          - `items` ParamShapeNode, required (recursive)
        - object
    - `queryParams` V2ApiConnectorsPostResponsesContentApplicationJsonSchemaParamsQueryParamsItems[], required: Query string parameters.
      - `key` string, required
      - `mode` 'static' | 'dynamic', required
      - `value` string, nullable
      - `type` 'array' | 'boolean' | 'number' | 'object' | 'raw' | 'string'
      - `shape` union
        - ParamShapeNode0
          - `type` ParamShapeNodeOneOf0TypeItems[], required
        - ParamShapeNode1
          - `type` ParamShapeNodeOneOf1TypeItems[], required
        - ParamShapeNode2
          - `type` ParamShapeNodeOneOf2TypeItems[], required
        - ParamShapeNode3
          - `type` ParamShapeNodeOneOf3TypeItems[], required
          - `properties` object, required
        - ParamShapeNode4
          - `type` ParamShapeNodeOneOf4TypeItems[], required
          - `items` ParamShapeNode, required (recursive)
        - object
    - `body` string, required: Raw request body template.
    - `bodyParams` V2ApiConnectorsPostResponsesContentApplicationJsonSchemaParamsBodyParamsItems[], required: Dynamic parameters extracted from `body`.
      - `key` string, required
      - `mode` 'static' | 'dynamic', required
      - `value` string, nullable
      - `type` 'array' | 'boolean' | 'number' | 'object' | 'raw' | 'string'
      - `shape` union
        - ParamShapeNode0
          - `type` ParamShapeNodeOneOf0TypeItems[], required
        - ParamShapeNode1
          - `type` ParamShapeNodeOneOf1TypeItems[], required
        - ParamShapeNode2
          - `type` ParamShapeNodeOneOf2TypeItems[], required
        - ParamShapeNode3
          - `type` ParamShapeNodeOneOf3TypeItems[], required
          - `properties` object, required
        - ParamShapeNode4
          - `type` ParamShapeNodeOneOf4TypeItems[], required
          - `items` ParamShapeNode, required (recursive)
        - object
  - `config` V2ApiConnectorsPostResponsesContentApplicationJsonSchemaConfig, required
    - `timeout` V2ApiConnectorsPostResponsesContentApplicationJsonSchemaConfigTimeout, required: Per-request timeout configuration.
      - `requestSec` number, double, required
    - `retry` V2ApiConnectorsPostResponsesContentApplicationJsonSchemaConfigRetry, required: Retry policy. `retryableStatusCodes` are HTTP codes that should trigger a retry.
      - `maxRetries` number, double, required
      - `retryableStatusCodes` number[], required
    - `redirects` V2ApiConnectorsPostResponsesContentApplicationJsonSchemaConfigRedirects, required: HTTP redirect handling.
      - `maxRedirects` number, double, required
    - `rateLimit` V2ApiConnectorsPostResponsesContentApplicationJsonSchemaConfigRateLimit, required: Rate limit applied to outbound requests from this connector.
      - `maxRequestsPerWindow` number, double, required
  - `createdBy` string, required: The identifier of the user who created this object.
  - `updatedBy` string, required: The identifier of the user or process that last updated this object.
  - `createdAt` string, date-time, required: When the object was created.
  - `updatedAt` string, date-time, required: When the object was last updated.
  - `description` string: Human-readable description.
  - `authId` string, nullable: Identifier of the API credential (`apiCredentialId`) used to authenticate requests. `null` if unauthenticated.

---

[API](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api.md) - [All operations](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/revisions/fb6036208c49?raw)