What does the request take?

The body has two fields, and there’s no channel field, because imports always go to the support agent. There’s no branch option either: the file is read from the repository’s default branch, and it can be up to 50,000 characters.

  • repo, required: owner/name, such as example-org/product-docs, or the repository’s address, https://github.com/example-org/product-docs. A trailing .git is dropped. Links to a branch, folder or file aren’t accepted.
  • path, optional: the file’s path in the repository, such as docs/getting-started.md, which defaults to README.md. It must end in .md, .mdx or .txt, be relative, with no leading slash and no . or .. segments, and be 250 characters or fewer. A new import is titled with the repository and path, and titles are limited to 140 characters, so owner/name and the path together must be 137 characters or fewer.
Import a file
curl -X POST 'https://app.kawlnow.com/api/manage/github' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"repo": "example-org/product-docs", "path": "docs/getting-started.md"}'

# Response 201: {"id": "SOURCE_ID"}, saved unapproved
Sources

What happens when you import the same file again?

The source is matched by repository and path. A repeat request replaces its text, updates updated_at, sets it back to unapproved, even when nothing changed, and returns 201 with the same id. Read the new text, then approve it again.

Until it’s approved again, the agent can’t use that file at all, so refresh and approve close together. Nothing watches the repository for changes, so send the request from your docs pipeline after a change is merged.

The source’s title is the repository and path, such as example-org/product-docs / docs/getting-started.md.

Which repositories can it read?

Public repositories work with no setup. Kawl Now reads them through GitHub’s REST API without a token. GitHub limits those requests by the address they come from, so every workspace’s public imports share one limit, and an import can fail with 502 for a while even if you’ve sent few. Wait, then try again.

A slow reply from GitHub, or a repository that has been renamed or moved, returns 400 with a short technical message, such as “fetch failed”. Retry once, then check the repository’s current address.

A private repository works only after Kawl Now has added it to your workspace’s server-side allowlist with a read-only token. You can’t set that up yourself, so ask before you rely on one. Until then, a private repository looks like a missing one and returns 404.

Sources

Which errors can it return?

Each error comes back as JSON with an error message:

  • 400 “Use a GitHub repository in owner/repository format.”: a repo value it can’t read.
  • 400 “Use a relative .md, .mdx, or .txt support document path.”: a path with another extension, a leading slash or dot segments.
  • 400 “Choose a support document smaller than 50,000 characters.”: split the file and import the parts.
  • 400 when the workspace already has 100 sources and the file is new to it.
  • 400 “Give your source a title, up to 140 characters.”: a new file whose repository and path together are too long for its title.
  • 400 with a short technical message, such as “fetch failed”: GitHub was slow to reply, or the repository has been renamed or moved.
  • 404 “Repository or document not found. Private repos require a read-only GitHub token.”: a typo, a private repository or a file that isn’t on the default branch.
  • 502 “GitHub could not sync this document. Check permissions and try again.”: GitHub refused or failed the request.