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

# Add a content source

> Maps a site URL prefix onto a GitHub repository folder (provider github, with installationId from getContentSources and repositoryId from listContentRepositories) or a GitBook space (provider gitbook, with connectionId, siteId and spaceId), with the checks Settings makes: GitHub must reach the repository, branch and folder, and the format is detected; the GitBook token must edit the space and GitBook must publish it at urlPrefix. Returns the source as the add recorded it, added by the member the key acts as. A failed check carries its reason: 400 invalid_prefix, invalid_folder, invalid_space, repository_unreachable, branch_not_found, folder_not_found, space_not_found, cannot_edit or prefix_not_published; 409 spaces_incomplete or cannot_list_sites. A prefix a live source already covers, a retry included, is 409 prefix_taken. An installationId or connectionId the account does not have is 404. One that is not active, or that GitHub refuses (a suspended app or an organization IP allow list), is 409 not_connected, and a rejected GitBook token 409 token_rejected, each with details.settingsUrl, the Settings page where a person reconnects it. Without content pull requests it is 403 content_pull_requests_unavailable, with details.settingsUrl, the account billing page. details.settingsUrl is null when no link can be built. A key whose member is not in the project or cannot manage DevTune is 403 cannot_manage_content. A GitHub or GitBook rate limit or outage is 503 with Retry-After. Requires the `setup.write` scope.



## OpenAPI

````yaml /openapi.json post /projects/{projectId}/setup/content-sources
openapi: 3.1.0
info:
  title: DevTune API
  version: 2.0.0
  description: >-
    API for programmatic access to your AI visibility data, webhook
    subscriptions, and automation workflows. Use this API to integrate DevTune
    data into CI/CD pipelines, BI tools, AI agents, and operational systems.
servers:
  - url: https://devtune.ai/api/v2
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Connection and usage
    description: >-
      The project a credential is bound to, its scopes and features, usage, and
      code-mode receipts.
  - name: Setup
    description: >-
      Brands, domains, brand terms, platforms, content sources and pausing a
      project.
  - name: Prompts and topics
    description: Tracked prompts, their topics, and prompt-set analysis.
  - name: Visibility
    description: >-
      Visibility metrics, AI answers, sentiment, competitive position and the
      project timeline.
  - name: Citations
    description: >-
      Citation statistics, the most-cited domains and pages, and cited lookalike
      sites.
  - name: Positioning
    description: How well AI answers match your positioning statements.
  - name: Accuracy
    description: Claims AI answers make about your brand, and contradictions.
  - name: Content gaps
    description: Topics, sources and brands where competitors are cited.
  - name: AI Traffic
    description: >-
      AI referrals, answer fetches, crawls, 404 Demand, Direct lift and Search
      Console totals.
  - name: Adoption
    description: npm downloads and GitHub stars for project domains.
  - name: Audit and pages
    description: Audit findings, Google eligibility, page metrics, and locked pages.
  - name: Actions
    description: Suggested and accepted work, briefs, drafts and pull requests.
  - name: Results
    description: Content changes, measured results and what works.
  - name: Agents
    description: Managed agents, their schedules and runs.
  - name: Dex
    description: Private Dex conversations, specialist handoffs and memory.
  - name: Agent Picks
    description: Agent Picks setup, tests, schedules and results.
  - name: Library and Knowledge
    description: Library items and the Knowledge Profile.
  - name: Webhooks
    description: Webhook subscriptions and signing secrets.
  - name: Agent registration
    description: Setup drafts for an unclaimed agent registration.
paths:
  /projects/{projectId}/setup/content-sources:
    post:
      tags:
        - Setup
      summary: Add a content source
      description: >-
        Maps a site URL prefix onto a GitHub repository folder (provider github,
        with installationId from getContentSources and repositoryId from
        listContentRepositories) or a GitBook space (provider gitbook, with
        connectionId, siteId and spaceId), with the checks Settings makes:
        GitHub must reach the repository, branch and folder, and the format is
        detected; the GitBook token must edit the space and GitBook must publish
        it at urlPrefix. Returns the source as the add recorded it, added by the
        member the key acts as. A failed check carries its reason: 400
        invalid_prefix, invalid_folder, invalid_space, repository_unreachable,
        branch_not_found, folder_not_found, space_not_found, cannot_edit or
        prefix_not_published; 409 spaces_incomplete or cannot_list_sites. A
        prefix a live source already covers, a retry included, is 409
        prefix_taken. An installationId or connectionId the account does not
        have is 404. One that is not active, or that GitHub refuses (a suspended
        app or an organization IP allow list), is 409 not_connected, and a
        rejected GitBook token 409 token_rejected, each with
        details.settingsUrl, the Settings page where a person reconnects it.
        Without content pull requests it is 403
        content_pull_requests_unavailable, with details.settingsUrl, the account
        billing page. details.settingsUrl is null when no link can be built. A
        key whose member is not in the project or cannot manage DevTune is 403
        cannot_manage_content. A GitHub or GitBook rate limit or outage is 503
        with Retry-After. Requires the `setup.write` scope.
      operationId: addContentSource
      parameters:
        - name: projectId
          in: path
          required: true
          description: >-
            The project the credential is bound to. Read it from GET
            /connection.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  additionalProperties: false
                  required:
                    - provider
                    - urlPrefix
                    - installationId
                    - repositoryId
                  properties:
                    provider:
                      type: string
                      const: github
                    urlPrefix:
                      type: string
                      minLength: 1
                      maxLength: 600
                      description: >-
                        The site address the source covers: a host and path such
                        as docs.example.com/ or example.com/blog/. A scheme,
                        query and fragment are dropped; the path is made to end
                        in a slash.
                    installationId:
                      type: string
                      format: uuid
                      description: >-
                        A GitHub installation id from getContentSources
                        githubInstallations.
                    repositoryId:
                      type: integer
                      minimum: 1
                      description: >-
                        A repository id listContentRepositories lists for the
                        installation.
                    branch:
                      type: string
                      maxLength: 255
                      description: >-
                        The branch pull requests target. Defaults to the
                        repository's default branch.
                    folder:
                      type: string
                      maxLength: 500
                      description: >-
                        The folder that holds the pages under urlPrefix, such as
                        docs. Defaults to the repository root.
                - type: object
                  additionalProperties: false
                  required:
                    - provider
                    - urlPrefix
                    - connectionId
                    - siteId
                    - spaceId
                  properties:
                    provider:
                      type: string
                      const: gitbook
                    urlPrefix:
                      type: string
                      minLength: 1
                      maxLength: 600
                      description: >-
                        The site address the source covers: a host and path such
                        as docs.example.com/ or example.com/blog/. A scheme,
                        query and fragment are dropped; the path is made to end
                        in a slash.
                    connectionId:
                      type: string
                      format: uuid
                      description: >-
                        A GitBook connection id from getContentSources
                        gitbookConnections.
                    siteId:
                      type: string
                      minLength: 1
                      maxLength: 128
                      description: The siteId of the space listContentRepositories lists.
                    spaceId:
                      type: string
                      minLength: 1
                      maxLength: 128
                      description: The spaceId listContentRepositories lists.
      responses:
        '200':
          description: The added source
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SetupContentSourceChange'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - data
                  - meta
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
        '503':
          headers:
            Retry-After:
              description: Seconds to wait before retrying a 429 or retryable 503 response.
              schema:
                type: integer
                minimum: 1
          description: GitHub or GitBook rate-limited the request or did not answer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SetupContentSourceChange:
      type: object
      additionalProperties: false
      required:
        - source
      properties:
        source:
          $ref: '#/components/schemas/SetupContentSource'
    Meta:
      type: object
      description: Sent beside data on every successful response that returns data.
      properties:
        timestamp:
          type: string
          format: date-time
          description: When the response was produced.
        projectId:
          type: string
          format: uuid
    Error:
      type: object
      properties:
        error:
          type: string
          description: >-
            Machine-readable error code, such as bad_request, unauthorized,
            forbidden, not_found, conflict, payment_required,
            rate_limit_exceeded or internal_error. Some endpoints return their
            own codes, listed in their descriptions.
        message:
          type: string
          description: >-
            What went wrong, for a person to read. Do not parse it; use error
            and reason.
        reason:
          type: string
          description: >-
            Why the request was refused, for an error with more than one cause,
            such as a refused content-draft start.
        details:
          type: object
          additionalProperties: true
          description: >-
            Machine-readable facts about the failure or refusal, such as
            retryable or shortfall_credits.
          properties:
            retryable:
              type: boolean
              description: >-
                Read this field before retrying. Present on every 5xx and 429
                response: true when another attempt may succeed, false for a
                permanent refusal even on a 5xx. Other refusals may also provide
                this field.
            retryAfterSeconds:
              type: integer
              minimum: 1
              description: >-
                Seconds to wait when retryable is true on a 429 or 503 response,
                also sent in Retry-After. Uses the provider retry time or
                limiter reset when available; otherwise 60 seconds for 429 and
                GitHub throttles or 30 seconds for other 503 responses. GitHub
                secondary limits wait at least 60 seconds.
        status:
          type: integer
          description: The HTTP status code, repeated in the body.
      required:
        - error
        - message
        - status
    SetupContentSource:
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - id
            - provider
            - urlPrefix
            - repository
            - branch
            - folder
            - format
            - status
            - reconnectReason
            - autoPullRequests
            - githubAccount
          properties:
            id:
              type: string
              format: uuid
            provider:
              type: string
              enum:
                - github
            urlPrefix:
              type: string
              description: >-
                A lowercase host and a path ending in a slash, with no scheme,
                such as docs.example.com/ or example.com/blog/.
            repository:
              type: string
              description: The GitHub repository, as owner/name.
            branch:
              type: string
              description: The repository branch the source reads.
            folder:
              type: string
              description: >-
                The folder in the repository, with no leading or trailing slash.
                Empty is the repository root.
            format:
              type: string
              enum:
                - mintlify
                - markdown
              description: >-
                mintlify for a Mintlify docs folder, markdown for plain Markdown
                files.
            status:
              type: string
              enum:
                - active
                - needs_reconnect
              description: >-
                needs_reconnect when DevTune lost access to the repository;
                reconnect GitHub in the app.
            reconnectReason:
              type:
                - string
                - 'null'
              enum:
                - installation
                - repository
                - null
              description: >-
                Why a needs_reconnect source broke: installation when the GitHub
                App was suspended or uninstalled, repository when the repository
                was removed from the app. Null while active.
            autoPullRequests:
              type: boolean
              description: >-
                Whether new drafts for pages under this source open pull
                requests automatically.
            githubAccount:
              type:
                - string
                - 'null'
              description: The GitHub organization or user the app is installed on.
        - type: object
          additionalProperties: false
          required:
            - id
            - provider
            - urlPrefix
            - space
            - connection
            - format
            - status
            - reconnectReason
            - autoPullRequests
          properties:
            id:
              type: string
              format: uuid
            provider:
              type: string
              enum:
                - gitbook
            urlPrefix:
              type: string
              description: >-
                A lowercase host and a path ending in a slash, with no scheme,
                such as docs.example.com/.
            space:
              type: object
              additionalProperties: false
              required:
                - id
                - title
              description: The GitBook space the prefix maps onto.
              properties:
                id:
                  type: string
                title:
                  type: string
            connection:
              type: object
              additionalProperties: false
              required:
                - organization
                - gitbookUser
              description: >-
                The GitBook connection the source uses: the organization, and
                the GitBook user whose token it is.
              properties:
                organization:
                  type: string
                gitbookUser:
                  type: string
            format:
              type: string
              enum:
                - gitbook
            status:
              type: string
              enum:
                - active
                - needs_reconnect
              description: >-
                needs_reconnect when the GitBook token stopped working or lost
                edit access to the space; replace the token in the app.
            reconnectReason:
              type:
                - string
                - 'null'
              enum:
                - token
                - space
                - null
              description: >-
                Why a needs_reconnect source broke: token when GitBook rejected
                the token, space when the token can no longer edit the space.
                Null while active.
            autoPullRequests:
              type: boolean
              description: >-
                Whether new drafts for pages under this source open change
                requests automatically.
  responses:
    BadRequestError:
      description: >-
        The request is invalid: a parameter or body field is missing, has the
        wrong type or is out of range, or a cursor doesn't match this list. The
        message says which; reason, where present, is listed in the endpoint's
        description. Fix the request before retrying, and restart a list without
        its cursor. See [Errors](/api-reference/errors).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnauthorizedError:
      description: >-
        The request has no valid credential: the Authorization header is missing
        or malformed, or the API key or OAuth token is invalid, expired or
        revoked. Send `Authorization: Bearer <API key>` with an active key, or
        sign in again to get a new OAuth token. See
        [Errors](/api-reference/errors).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ForbiddenError:
      description: >-
        The credential is valid but can't make this request. The message says
        which cause applies: the key or sign-in lacks the scope this endpoint
        requires (named in the message), it belongs to another project, the plan
        doesn't include API access or this feature, the project is paused (a
        paused project keeps only read scopes and setup.write), or the member a
        write acts as no longer has the role it needs. Read `GET
        /projects/{projectId}/connection` for the credential's current scopes
        and features, then use a key that has the scope, sign in again and
        approve it, or upgrade the plan. See [Errors](/api-reference/errors).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFoundError:
      description: >-
        The resource doesn't exist in this project, was deleted, or the
        credential can't see it. Check the IDs in the path, and that the
        projectId is the project the credential is bound to. See
        [Errors](/api-reference/errors).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ConflictError:
      description: >-
        The request conflicts with the resource's current state. The message,
        and reason where present, say what conflicts; the endpoint's description
        lists its reasons. Read the resource again, then change the request.
        When the body has retryable true, send the same request again. See
        [Errors](/api-reference/errors).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimitExceededError:
      description: >-
        Too many requests from this credential in the current window. The
        request was refused before it took effect, so it is safe to retry: wait
        the seconds in Retry-After, then send it again. Endpoints that start
        agent runs have a stricter limit. See [Rate
        limits](/api-reference/rate-limits).
      headers:
        Retry-After:
          description: Seconds to wait before retrying a 429 or retryable 503 response.
          schema:
            type: integer
            minimum: 1
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    X-RateLimit-Limit:
      description: Maximum requests per window
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests remaining in current window
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix timestamp when the window resets
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key with dtk_live_ prefix. Obtain it from API Keys in the account
        sidebar. New keys start with all supported scopes selected for the
        chosen project, and you can narrow them to specific read/write scopes as
        needed.

````

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