> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a workspace connection (beta)

> Creates a workspace connection from the supplied configuration and credentials, and returns its metadata without credentials. Requires workspace_integration_management:write.

Open Beta (This feature is currently in open beta. We are actively improving it based on your feedback. If you encounter any issues or have suggestions, please share them on our Discord community or visit the support page.)

> [tab] CLI Tool
>
> ```bash
> coderabbit api request /connections --input request.json
> ```
>
> To install and sign in to the CLI, see [Call from the CLI](https://docs.coderabbit.ai/api/cli.md).

> [tab] MCP Server
>
> An agent connected to the [CodeRabbit MCP server](https://docs.coderabbit.ai/api/mcp.md) runs this operation as the `create_connection` tool. The connection selects the organization, so the arguments have no `org_id` or `org_name`.
>
> ```json
> {
>   "method": "tools/call",
>   "params": {
>     "name": "create_connection",
>     "arguments": {
>       "connection": {}
>     }
>   }
> }
> ```


## OpenAPI

````yaml /openapi.json post /v1/connections
openapi: 3.0.0
info:
  title: CodeRabbit API
  version: 1.0.0
  description: >-
    Read and manage CodeRabbit reviews, coding tasks, Verify, Triage, security
    findings, Knowledge Base, configuration, and users for your organization.
servers:
  - url: https://api.coderabbit.ai
    description: US region
  - url: https://api.eu.coderabbit.ai
    description: EU region
security:
  - ApiKeyAuth: []
tags:
  - name: Organizations and repositories
  - name: Pull requests and reviews
  - name: Coding Agent
  - name: Coding environments
  - name: Verify
  - name: Triage
  - name: Security
  - name: Knowledge Base
  - name: Automations
  - name: Reports
  - name: Configuration
  - name: Connections
  - name: Users and roles
  - name: Usage and metrics
paths:
  /v1/connections:
    post:
      tags:
        - Connections
      summary: Create a workspace connection
      description: >-
        Creates a workspace connection from the supplied configuration and
        credentials, and returns its metadata without credentials. Requires
        workspace_integration_management:write.
      operationId: create_connection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                org_id:
                  type: string
                  minLength: 1
                  description: >-
                    Organization for a workspace key: the Git-provider
                    organization ID (scope.provider_organization_id) or the
                    CodeRabbit organization ID (scope.id, or id from list
                    organizations). Supply either org_id or org_name, never
                    both. Omit for organization keys and MCP connections.
                org_name:
                  type: string
                  pattern: ^[A-Za-z0-9][A-Za-z0-9-]{0,38}$
                  description: >-
                    GitHub organization login, such as coderabbitai, not its
                    display name. Matched case-insensitively within the
                    authenticated workspace. Supply either org_name or org_id,
                    never both; omit for organization keys and MCP connections.
                connection:
                  type: object
                  properties:
                    salesforceServiceAccount:
                      anyOf:
                        - type: object
                          properties:
                            flow:
                              enum:
                                - client_credentials
                            clientId:
                              type: string
                              minLength: 1
                              maxLength: 2000
                            myDomainUrl:
                              type: string
                              maxLength: 2000
                          required:
                            - flow
                            - clientId
                            - myDomainUrl
                          additionalProperties: false
                        - type: object
                          properties:
                            flow:
                              enum:
                                - jwt_bearer
                            clientId:
                              type: string
                              minLength: 1
                              maxLength: 2000
                            environment:
                              enum:
                                - production
                                - sandbox
                              type: string
                            username:
                              type: string
                              minLength: 1
                              maxLength: 320
                          required:
                            - flow
                            - clientId
                            - environment
                            - username
                          additionalProperties: false
                    sourceId:
                      enum:
                        - amplemarket
                        - asana
                        - aws
                        - azure_devops
                        - bigquery
                        - bitbucket
                        - canva
                        - circleci
                        - custom
                        - customer_io
                        - datadog
                        - figma
                        - gcp
                        - google_cloud
                        - github
                        - gitlab
                        - gitlab_self_hosted
                        - gdrive
                        - google_ads
                        - google_analytics
                        - google_calendar
                        - google_search_console
                        - gong
                        - intercom
                        - jenkins
                        - jira
                        - linkedin_ads
                        - linear
                        - notion
                        - onedrive
                        - pagerduty
                        - pylon
                        - posthog
                        - reddit_ads
                        - x_ads
                        - salesforce
                        - semrush
                        - sentry
                        - trello
                        - zendesk
                        - hubspot
                      type: string
                    connectionName:
                      type: string
                      minLength: 2
                      maxLength: 160
                    description:
                      type: string
                      maxLength: 10000
                    authKind:
                      enum:
                        - oauth
                        - service_account
                        - api_keys
                        - mcp
                        - webhook
                      type: string
                    connectionPurpose:
                      enum:
                        - runtime_access
                        - trigger_source
                      type: string
                      default: runtime_access
                    policyMode:
                      enum:
                        - read_only
                        - read_write
                      type: string
                    oauth:
                      type: object
                      properties:
                        connected:
                          type: boolean
                          default: false
                        accountEmail:
                          type: string
                          maxLength: 320
                          format: email
                        accountLabel:
                          type: string
                          maxLength: 200
                        grantedScopes:
                          type: array
                          maxItems: 512
                          items:
                            type: string
                            minLength: 1
                            maxLength: 500
                        connectedAt:
                          type: string
                          format: date-time
                      required:
                        - grantedScopes
                    gdriveServiceAccount:
                      type: object
                      properties:
                        clientEmail:
                          type: string
                          minLength: 1
                          maxLength: 320
                          format: email
                        privateKeyId:
                          type: string
                          minLength: 1
                          maxLength: 255
                        clientId:
                          type: string
                          minLength: 1
                          maxLength: 255
                        projectId:
                          type: string
                          minLength: 1
                          maxLength: 255
                        validatedAt:
                          type: string
                          format: date-time
                      required:
                        - clientEmail
                    googleServiceAccount:
                      type: object
                      properties:
                        clientEmail:
                          type: string
                          minLength: 1
                          maxLength: 320
                          format: email
                        privateKeyId:
                          type: string
                          minLength: 1
                          maxLength: 255
                        clientId:
                          type: string
                          minLength: 1
                          maxLength: 255
                        projectId:
                          type: string
                          minLength: 1
                          maxLength: 255
                        impersonatedUserEmail:
                          type: string
                          minLength: 1
                          maxLength: 320
                          format: email
                        validatedAt:
                          type: string
                          format: date-time
                      required:
                        - clientEmail
                    fieldValues:
                      type: object
                      additionalProperties:
                        type: string
                        maxLength: 2000
                      x-propertyNames:
                        type: string
                        minLength: 1
                        maxLength: 200
                      description: >-
                        Property names must contain at least 1 character and at
                        most 200 characters.
                    apiKeys:
                      type: array
                      maxItems: 30
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            minLength: 1
                            maxLength: 200
                          name:
                            type: string
                            minLength: 1
                            maxLength: 120
                          value:
                            type: string
                            minLength: 1
                            maxLength: 20000
                        required:
                          - id
                          - name
                          - value
                    envVars:
                      type: array
                      maxItems: 30
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            minLength: 1
                            maxLength: 200
                          name:
                            type: string
                            minLength: 1
                            maxLength: 120
                          value:
                            type: string
                            minLength: 1
                            maxLength: 20000
                        required:
                          - id
                          - name
                          - value
                      default: []
                    mcp:
                      type: object
                      properties:
                        enabled:
                          type: boolean
                        serverName:
                          type: string
                          maxLength: 240
                        serverUrl:
                          type: string
                          maxLength: 2000
                        transport:
                          enum:
                            - sse
                            - streamable_http
                            - websocket
                          type: string
                        authMethod:
                          enum:
                            - none
                            - api_keys
                            - oauth
                          type: string
                        authHeaderName:
                          type: string
                          maxLength: 200
                        authHeaderValue:
                          type: string
                          maxLength: 20000
                        allowedTools:
                          type: array
                          items:
                            type: string
                            minLength: 1
                          readOnly: true
                      required:
                        - enabled
                        - serverName
                        - serverUrl
                        - transport
                        - authHeaderName
                        - authHeaderValue
                    expectedUpdatedAt:
                      type: string
                      format: date-time
                    salesforceServiceAccountSecret:
                      anyOf:
                        - type: object
                          properties:
                            flow:
                              enum:
                                - client_credentials
                            clientSecret:
                              type: string
                              minLength: 1
                              maxLength: 20000
                          required:
                            - flow
                            - clientSecret
                          additionalProperties: false
                        - type: object
                          properties:
                            flow:
                              enum:
                                - jwt_bearer
                            privateKey:
                              type: string
                              minLength: 1
                              maxLength: 20000
                          required:
                            - flow
                            - privateKey
                          additionalProperties: false
                    gdriveServiceAccountKey:
                      type: object
                      properties:
                        clientEmail:
                          type: string
                          minLength: 1
                          maxLength: 320
                          format: email
                        privateKey:
                          type: string
                          minLength: 1
                          maxLength: 20000
                        privateKeyId:
                          type: string
                          minLength: 1
                          maxLength: 255
                        clientId:
                          type: string
                          minLength: 1
                          maxLength: 255
                        tokenUri:
                          type: string
                          maxLength: 2000
                          format: uri
                        projectId:
                          type: string
                          minLength: 1
                          maxLength: 255
                      required:
                        - clientEmail
                        - privateKey
                        - privateKeyId
                        - clientId
                        - tokenUri
                    googleServiceAccountKey:
                      type: object
                      properties:
                        clientEmail:
                          type: string
                          minLength: 1
                          maxLength: 320
                          format: email
                        privateKey:
                          type: string
                          minLength: 1
                          maxLength: 20000
                        privateKeyId:
                          type: string
                          minLength: 1
                          maxLength: 255
                        clientId:
                          type: string
                          maxLength: 255
                        tokenUri:
                          type: string
                          maxLength: 2000
                          format: uri
                        projectId:
                          type: string
                          minLength: 1
                          maxLength: 255
                        impersonatedUserEmail:
                          type: string
                          minLength: 1
                          maxLength: 320
                          format: email
                      required:
                        - clientEmail
                        - privateKey
                        - privateKeyId
                        - clientId
                        - tokenUri
                  required:
                    - sourceId
                    - connectionName
                    - description
                    - fieldValues
                    - apiKeys
                    - mcp
                mcpSettings:
                  type: object
                  properties:
                    userPrompt:
                      type: string
                      maxLength: 10000
                    custom_headers:
                      type: string
                      maxLength: 3000
              required:
                - connection
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  connection:
                    type: object
                    properties:
                      integrationId:
                        type: string
                        format: uuid
                      sourceId:
                        enum:
                          - amplemarket
                          - asana
                          - aws
                          - azure_devops
                          - bigquery
                          - bitbucket
                          - canva
                          - circleci
                          - custom
                          - customer_io
                          - datadog
                          - figma
                          - gcp
                          - google_cloud
                          - github
                          - gitlab
                          - gitlab_self_hosted
                          - gdrive
                          - google_ads
                          - google_analytics
                          - google_calendar
                          - google_search_console
                          - gong
                          - intercom
                          - jenkins
                          - jira
                          - linkedin_ads
                          - linear
                          - notion
                          - onedrive
                          - pagerduty
                          - pylon
                          - posthog
                          - reddit_ads
                          - x_ads
                          - salesforce
                          - semrush
                          - sentry
                          - trello
                          - zendesk
                          - hubspot
                        type: string
                      connectionName:
                        type: string
                        minLength: 2
                        maxLength: 160
                      description:
                        type: string
                        maxLength: 10000
                      connectionPurpose:
                        enum:
                          - runtime_access
                          - trigger_source
                        type: string
                        default: runtime_access
                      policyMode:
                        enum:
                          - read_only
                          - read_write
                        type: string
                      updatedAt:
                        type: string
                        format: date-time
                      requiresReconnect:
                        type: boolean
                        default: false
                      hasOAuthGrant:
                        type: boolean
                      mcp:
                        type: object
                        properties:
                          enabled:
                            type: boolean
                          serverOrigin:
                            anyOf:
                              - type: string
                              - type: string
                                nullable: true
                                enum:
                                  - null
                          transport:
                            enum:
                              - sse
                              - streamable_http
                              - websocket
                            type: string
                          authMethod:
                            enum:
                              - none
                              - api_keys
                              - oauth
                            type: string
                          allowedTools:
                            type: array
                            items:
                              type: string
                        required:
                          - enabled
                          - serverOrigin
                          - transport
                    required:
                      - integrationId
                      - sourceId
                      - connectionName
                      - description
                      - updatedAt
                      - mcp
                required:
                  - ok
                  - connection
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - invalid_request
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - unauthenticated
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - forbidden
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - not_found
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - head_changed
                          - conflict
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '412':
          description: Precondition failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - precondition_failed
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '413':
          description: Content too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - payload_too_large
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - rate_limit_exceeded
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        enum:
                          - internal_error
                        type: string
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - unavailable
                      message:
                        type: string
                      retry_after:
                        type: integer
                        minimum: 0
                        exclusiveMinimum: true
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-coderabbitai-api-key
      description: >-
        See [Authentication](/api/authentication) for the key types and where to
        create a key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.