Mintlify Integration (GitHub)

Mintlify is a documentation platform that generates beautiful docs sites from Markdown and MDX files stored in a GitHub repository. Every push to the tracked branch triggers an automatic redeploy of the docs site.

LaunchBrightly integrates with Mintlify by connecting directly to the underlying GitHub repository via a GitHub App. This allows LaunchBrightly to import articles from your docs repo and sync updated screenshots by opening pull requests with replacement images.

💡 How it differs from other Help Center integrations

Zendesk, Intercom and other help center integrations update articles via each platform's REST API. Mintlify integrations work through Git: LaunchBrightly reads your MDX/MD files from the repo, matches screenshots by metadata or hash and commits replacement images to a new branch. A pull request is opened (and optionally auto-merged) so the change flows through your normal review process.

Prerequisites

Before creating a Mintlify integration, you need:

A GitHub repository containing your Mintlify docs (MDX or Markdown files).
A LaunchBrightly API key. See Getting Started.

Create a Mintlify integration

POST /integration

Request

json

{
  "label": "Acme Docs (Mintlify)",
  "provider": "mintlify",
  "platform": "github",
  "credentials": {
    "installationId": "12345678",
    "owner": "your-org",
    "repo": "your-docs-repo",
    "branch": "main",
    "docs": "docs",
    "siteUrl": "https://docs.your-domain.com"
  }
}

cURL

bash

curl --location --request POST 'https://api.launchbrightly.com/integration' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "label": "Acme Docs (Mintlify)",
  "provider": "mintlify",
  "platform": "github",
  "credentials": {
    "installationId": "12345678",
    "owner": "your-org",
    "repo": "your-docs-repo",
    "branch": "main",
    "docs": "docs",
    "siteUrl": "https://docs.your-domain.com"
  }
}'

Field reference

Field	Type	Required	Description
`label`	string	Yes	A human-readable label for this integration.
`provider`	string	Yes	Must be `mintlify`.
`platform`	string	Yes	Must be `github`.
`credentials.installationId`	string	Yes	The GitHub App installation ID, provided during app installation.
`credentials.owner`	string	No*	The GitHub organization or username that owns the repository (e.g., `your-org`).
`credentials.repo`	string	No*	The repository name (e.g., `your-docs-repo`).
`credentials.branch`	string	No	The branch to track. Defaults to `main` when omitted.
`credentials.docs`	string	No	The docs folder relative to the repo root (e.g., `docs`). When omitted, the entire repository is scanned for MDX/MD files.
`credentials.siteUrl`	string	No	The public URL of your docs site (e.g., `https://docs.your-domain.com`). When set, article links in LaunchBrightly point here instead of GitHub.

INFO

*owner and repo can be omitted on initial creation and set later via PUT /integration. The verification endpoint returns all accessible repositories and branches so you can present a picker in your UI before finalizing the configuration.

Success Response

Code: `200`

json

{
  "id": "d9e45598-d24d-40d8-baf6-33b6185c61b3",
  "createdAt": "2026-06-15T10:30:00.000Z",
  "updatedAt": "2026-06-15T10:30:00.000Z",
  "message": "The Integration credentials have been successfully created."
}

Error Response - Code: `422`

json

{
  "errors": [
    "The platform is not supported. Supported platforms: github, helpcenter, cloud"
  ]
}

Update an existing integration

PUT /integration

The Mintlify integration supports partial credential updates. You can send only the fields you want to change - they are merged with the stored credentials automatically. This is useful for updating owner, repo, or branch after initial creation.

Request

cURL

bash

curl --location --request PUT 'https://api.launchbrightly.com/integration' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "id": "d9e45598-d24d-40d8-baf6-33b6185c61b3",
  "label": "Acme Docs (Mintlify)",
  "provider": "mintlify",
  "platform": "github",
  "credentials": {
    "owner": "your-org",
    "repo": "your-docs-repo",
    "branch": "production"
  }
}'

Fields not included in credentials (like installationId) retain their stored values.

Success Response

Code: `200`

json

{
  "id": "d9e45598-d24d-40d8-baf6-33b6185c61b3",
  "createdAt": "2026-06-15T10:30:00.000Z",
  "updatedAt": "2026-06-15T10:45:00.000Z",
  "message": "The Integration credentials have been successfully updated."
}

Verify connection

POST /integration/verify

Verifies that the GitHub App installation is valid and returns the list of accessible repositories and their branches. Use this to build a repository/branch picker before finalizing the integration.

Request

cURL

bash

curl --location --request POST 'https://api.launchbrightly.com/integration/verify' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "integrationId": "d9e45598-d24d-40d8-baf6-33b6185c61b3"
}'

Success Response

Code: `200`

json

{
  "isConnectionSuccessful": true,
  "message": "The GitHub credentials have been successfully validated.",
  "meta": [
    {
      "owner": "your-org",
      "repo": "your-docs-repo",
      "branches": ["main", "staging", "production"]
    },
    {
      "owner": "your-org",
      "repo": "blog",
      "branches": ["main"]
    }
  ]
}

The meta array contains every repository accessible to the GitHub App installation, along with their branch names.

Failure Response

Condition: Installation ID not found or the GitHub App is not installed

json

{
  "isConnectionSuccessful": false,
  "message": "Installation not found or this GitHub App is not installed for that installation id."
}

Import articles from a Mintlify repo

POST /helpcenter/import

Imports all MDX and Markdown articles from the configured repository and branch. The import process scans the docs directory (or the entire repo if docs is not set), extracts frontmatter metadata and inline images and creates article records in LaunchBrightly.

Request

cURL

bash

curl --location --request POST 'https://api.launchbrightly.com/helpcenter/import' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "integrationId": "d9e45598-d24d-40d8-baf6-33b6185c61b3"
}'

Success Response

Code: `202 Accepted`

json

{
  "import_job_id": "5592eac6-dfaf-47b8-890a-b6d7cdd7b0ac",
  "platform": "github",
  "message": "Your import request has been received successfully"
}

Use GET /helpcenter/import/:import_job_id to poll for import progress. See Import using Auth for full response details.

INFO

GitHub articles use the file path as their external_article_id (e.g., docs/getting-started.mdx). This is the same identifier you'll use as the articleId when syncing screenshots.

Sync screenshots to Mintlify

POST /helpcenter/article/async

Screenshot updates for Mintlify integrations must use the asynchronous endpoint. The synchronous PUT /helpcenter/article/:id endpoint is not supported for GitHub integrations and returns a 501 error.

See Asynchronous Article Updates for full endpoint documentation.

How it works

When you submit a batch of screenshot updates targeting a Mintlify integration:

All jobs are coalesced into a single SQS message keyed by articleRequestId, rather than one message per screenshot. This ensures one pull request per batch.
The worker creates a branch named lb-<articleRequestId> off the configured base branch.
For each article in the batch, the worker reads the live MDX/MD content from the base branch, matches incoming screenshots against the images in the file (using the standard metadata → hash priority), downloads the replacement image and writes it as a new blob.
One commit is created per article with the message format: screenshot: update N image(s) in <path>.
A pull request is opened from the working branch back to the base branch, titled with a summary of the changes.
If automergePR is true, the pull request is automatically merged after creation.

Request example

cURL

bash

curl --location --request POST 'https://api.launchbrightly.com/helpcenter/article/async' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "integrationId": "d9e45598-d24d-40d8-baf6-33b6185c61b3",
  "automergePR": true,
  "data": [
    {
      "articleId": "docs/billing/overview.mdx",
      "screenshots": [
        {
          "metadata": { "name": "John", "surname": "Doe" },
          "hash": "4d441888f21eceed2443eef4ba9b4e4d6c198f86904c258d476fed10a6b2e555",
          "name": "billing-dashboard.png",
          "url": "https://your-bucket.s3.us-east-1.amazonaws.com/your-team/2026-01-15/screenshot-001.png"
        }
      ]
    },
    {
      "articleId": "docs/settings/general.mdx",
      "screenshots": [
        {
          "metadata": { "name": "Jane" },
          "hash": "b6975b10b36df3cc8e41b16a9be8c4f691aa1a2059d3dbcfde31d16fe6d5f65d",
          "name": "settings-page.png",
          "url": "https://your-bucket.s3.us-east-1.amazonaws.com/your-team/2026-01-15/screenshot-002.png"
        }
      ]
    }
  ]
}'

INFO

The articleId for Mintlify integrations is the file path within the repository (e.g., docs/billing/overview.mdx), not a numeric ID. This is the same path returned as external_article_id during import.

Success Response

Code: `202 Accepted`

json

{
  "articleRequestId": "c3a1f9e2-7b4d-4e8a-9f5c-2d6b8a3e1f7d",
  "jobs": [
    {
      "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
      "status": "pending",
      "createdAt": "2026-06-15T10:30:00.000Z"
    },
    {
      "id": "f9e8d7c6-5b4a-3210-fedc-ba9876543210",
      "status": "pending",
      "createdAt": "2026-06-15T10:30:00.000Z"
    }
  ]
}

Polling response (GitHub-specific fields)

When polling GET /helpcenter/article/request/:articleRequestId for a Mintlify batch, the response includes GitHub-specific fields alongside the standard summary and jobs:

cURL

bash

curl --location --request GET 'https://api.launchbrightly.com/helpcenter/article/request/c3a1f9e2-7b4d-4e8a-9f5c-2d6b8a3e1f7d' \
--header 'x-api-key: YOUR_API_KEY'

Code: `200 OK`

json

{
  "summary": {
    "total": "2",
    "pending": "0",
    "completed": "2",
    "failed": "0",
    "delayed": "0"
  },
  "pullRequestUrl": "https://github.com/your-org/your-docs-repo/pull/42",
  "pullRequestMerged": true,
  "branch": "lb-c3a1f9e2-7b4d-4e8a-9f5c-2d6b8a3e1f7d",
  "jobs": [
    {
      "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
      "externalArticleId": "docs/billing/overview.mdx",
      "name": "billing-dashboard.png",
      "metadata": { "name": "John", "surname": "Doe" },
      "hash": "4d441888f21eceed2443eef4ba9b4e4d6c198f86904c258d476fed10a6b2e555",
      "matchType": "metadata",
      "status": "completed",
      "createdAt": "2026-06-15T10:30:00.000Z",
      "updatedAt": "2026-06-15T10:30:15.000Z"
    },
    {
      "id": "f9e8d7c6-5b4a-3210-fedc-ba9876543210",
      "externalArticleId": "docs/settings/general.mdx",
      "name": "settings-page.png",
      "metadata": { "name": "Jane" },
      "hash": "b6975b10b36df3cc8e41b16a9be8c4f691aa1a2059d3dbcfde31d16fe6d5f65d",
      "matchType": "name",
      "status": "completed",
      "createdAt": "2026-06-15T10:30:00.000Z",
      "updatedAt": "2026-06-15T10:30:18.000Z"
    }
  ]
}

Field	Description
`pullRequestUrl`	Full URL to the GitHub pull request. `null` if no images were matched.
`pullRequestMerged`	`true` if the PR was auto-merged (requires `automergePR: true`).
`branch`	The working branch name: `lb-<articleRequestId>`.

Key differences from other integrations

Aspect	Zendesk / Intercom / etc.	Mintlify (GitHub)
Integration platform	`helpcenter`	`github`
Integration provider	`zendesk`, `intercom`, etc.	`mintlify`
Article identifier	Numeric external article ID	File path (e.g., `docs/overview.mdx`)
Sync method	Async POST (one SQS message per screenshot)	Async POST (one SQS message per batch)
Output	Direct API call to help center	Git commit + pull request
Duplicate detection	30s delay + retry per article	Not needed (single batch processing)
Sync PUT endpoint	Supported (legacy)	Not supported (returns `501`)

Supported file types

Extension	Type
`.md`	Markdown
`.mdx`	MDX (Markdown with JSX)

Files outside the configured docs directory (if set) are ignored.

Image matching in MDX files

The worker reads each MDX/MD file from the repository and extracts all image references. It then uses the same matching priority as other integrations:

Priority	Match Type	How it matches in MDX
1st	`metadata`	Compares the screenshot's metadata key-value pairs against PNG metadata embedded in the live image
2nd	`hash`	Compares the pixel hash of the incoming screenshot against the live image

When a match is found, the replacement image is committed to the repository under the same directory as the original (or under images/launchbrightly/ for new paths) and the MDX image reference is updated accordingly.

HTTP status codes

Code	Endpoint	Description
`200`	`POST /integration`, `PUT /integration`, `POST /integration/verify`, `GET /helpcenter/article/request/:id`	Success
`202`	`POST /helpcenter/import`, `POST /helpcenter/article/async`	Accepted for async processing
`403`	All	Missing or invalid API key
`404`	`GET /helpcenter/article/request/:id`	`articleRequestId` not found
`422`	`POST /integration`, `PUT /integration`, `POST /helpcenter/article/async`	Validation error
`500`	All	Unexpected server error
`501`	`PUT /helpcenter/article/:id`	GitHub integrations do not support synchronous updates

Mintlify Integration (GitHub) ​

Prerequisites ​

Create a Mintlify integration ​

Request ​

cURL ​

Field reference ​

Success Response ​

Code: 200 ​

Error Response - Code: 422 ​

Update an existing integration ​

Request ​

cURL ​

Success Response ​

Code: 200 ​

Verify connection ​

Request ​

cURL ​

Success Response ​

Code: 200 ​

Failure Response ​

Condition: Installation ID not found or the GitHub App is not installed ​

Import articles from a Mintlify repo ​

Request ​

cURL ​

Success Response ​

Code: 202 Accepted ​

Sync screenshots to Mintlify ​

How it works ​

Request example ​

cURL ​

Success Response ​

Code: 202 Accepted ​

Polling response (GitHub-specific fields) ​

cURL ​

Code: 200 OK ​

Key differences from other integrations ​

Supported file types ​

Image matching in MDX files ​

HTTP status codes ​

Mintlify Integration (GitHub)

Prerequisites

Create a Mintlify integration

Request

cURL

Field reference

Success Response

Code: `200`

Error Response - Code: `422`

Update an existing integration

Request

cURL

Success Response

Code: `200`

Verify connection

Request

cURL

Success Response

Code: `200`

Failure Response

Condition: Installation ID not found or the GitHub App is not installed

Import articles from a Mintlify repo

Request

cURL

Success Response

Code: `202 Accepted`

Sync screenshots to Mintlify

How it works

Request example

cURL

Success Response

Code: `202 Accepted`

Polling response (GitHub-specific fields)

cURL

Code: `200 OK`

Key differences from other integrations

Supported file types

Image matching in MDX files

HTTP status codes