---
title: "Create a source-control integration."
method: POST
path: "/v1/integrations"
tags: ["Integrations"]
---

# Create a source-control integration.

`POST /v1/integrations`

## Request

- Base URL: `https://api.scalix.world`
- URL: `https://api.scalix.world/v1/integrations`
- Auth: HTTP bearer

Attaches a Git provider repo to the caller's project and returns the created
integration plus the webhook URL and secret to configure on the provider.

## Request body

- CreateIntegrationBody: Request body for `POST /v1/integrations`.
  - `provider` string, required: One of `github`, `gitlab`, `bitbucket`.
  - `repo_url` string, required
  - `branch_filter` string, nullable
  - `auto_build` boolean, nullable
  - `auto_deploy` boolean, nullable
  - `service_id` string, nullable
  - `function_id` string, nullable: Function deploy target: every later build PUTs the fresh image onto this function (drains its warm pool + re-warms the new revision). Mutually exclusive with `service_id` — one repo deploys one thing, and the tenant chooses which.
  - `preview_enabled` boolean, nullable
  - `preview_ttl_hours` integer, nullable

## Response `201`

Integration created; returns webhook URL + secret

- CreateIntegrationResponse: Response for `POST /v1/integrations` — the created integration plus the webhook URL and secret to configure on the provider.
  - `integration` IntegrationJson, required: A source-control integration (GitHub/GitLab/Bitbucket) attached to a project.
    - `id` string, required
    - `project_id` string, required
    - `provider` string, required
    - `repo_url` string, required
    - `branch_filter` string, required
    - `auto_build` boolean, required
    - `auto_deploy` boolean, required
    - `status` string, required
    - `service_id` string, nullable
    - `function_id` string, nullable
    - `preview_enabled` boolean, required
    - `preview_ttl_hours` integer, required
    - `created_at` string, required
    - `updated_at` string, required
  - `webhook_url` string, required
  - `webhook_secret` string, required

## Other responses

- `400`: Invalid provider or duplicate integration
- `401`: Missing or invalid credentials
- `500`: Internal error

---

[API](https://skmtc.dev/scalix/apis/scalix-cloud-api.md) · [All operations](https://skmtc.dev/scalix/apis/scalix-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalix/apis/scalix-cloud-api/revisions/2c04ca0a90bb?raw)