AdaptsAPI Client

A Python client library and CLI for the Adapts API: chat with your codebase wikis, generate wiki docs, and read / generate release notes.

Installation

pip install adaptsapi

Getting Your API Token

1. Log in to adapts.app
2. Go to Settings → API Token
3. Generate a new token and copy it

Set the token as an environment variable:

export ADAPTS_API_KEY="your-api-token-here"

Or pass it directly when creating the client:

from adaptsapi import AdaptsClient

client = AdaptsClient(api_key="your-api-token-here")

Quick Start

Using the Python Client (Recommended)

from adaptsapi import AdaptsClient

client = AdaptsClient()  # uses ADAPTS_API_KEY env var

# List wikis available for chat
wikis = client.list_chat_enabled_wikis()

# Chat (blocks until response is ready)
response = client.chat("What does this repo do?", wiki_name="my-repo_main")
print(response["response"])

# Chat across multiple wikis
response = client.chat("Compare these repos.", wiki_names=["wiki_a", "wiki_b"])

# Follow-up in same thread
response = client.chat(
    "Can you elaborate?",
    wiki_name="my-repo_main",
    thread_id=response["thread_id"],
)

# Async chat (returns immediately, poll manually)
started = client.chat_async("Explain the auth flow.", wiki_name="my-repo_main")
status = client.poll_chat_status(started["thread_id"], started["created_on"])

# List all wiki generation requests
all_wikis = client.list_all_wikis()

# List release notes (org-wide)
page = client.list_release_notes(limit=10)
for row in page["rows"]:
    note = client.get_release_note(row["wiki_id"], row["release_id"])
    print(note["content"])

# Filter by wiki
client.list_release_notes(wiki_id="my-org/my-repo", limit=5)

# Generate wiki documentation
connections = client.list_git_connections()
connection_id = connections[0]["connection_id"]
repos = client.list_git_repos(connection_id)
client.generate_wiki(
    connection_id=connection_id,
    repo_url=repos[0]["repo_url"],
    branch="main",
    wiki_name="my-repo_main",
)

Using the CLI

Chat:

adaptsapi --chat --data '{"user_prompt":"What does this do?","wiki_name":"my-repo_main"}'

Chat status (poll for response):

adaptsapi --chat-status --data '{"thread_id":"uuid-from-chat","created_on":"timestamp-from-chat"}'

List chat-enabled wikis:

adaptsapi --chat-enabled-wikis

List all wikis:

adaptsapi --list-wikis

Read release notes:

adaptsapi --list-release-notes
adaptsapi --list-release-notes --data '{"limit":10}'
adaptsapi --list-release-notes --data '{"wiki_id":"my-org/my-repo","limit":5}'
adaptsapi --get-release-note --data '{"wiki_id":"...","release_id":"..."}'

Generate docs:

adaptsapi --list-git-connections
adaptsapi --list-git-repos --data '{"connection_id":"GIT_github_org"}'
adaptsapi --generatedoc \
  --data '{"connection_id":"GIT_github_org","repo_url":"https://github.com/org/repo","branch":"main","wiki_name":"repo_main"}'

Generate docs (payload file):

adaptsapi --generatedoc --payload-file payload.json

Generate release notes:

adaptsapi --releasenotes --payload-file payload.json

Python Client Reference

AdaptsClient

client = AdaptsClient(api_key=None, base_url=None, timeout=30)

Auto-resolves api_key from ADAPTS_API_KEY / ADAPTS_API_TOKEN env var if omitted.

Chat

Chat parameters:

Wiki Listing

Git connections (for wiki generate)

Release Notes (Read)

list_release_notes parameters (all optional; org comes from your API key — do not send org_id):

Generate Wiki

client.generate_wiki(
    connection_id="GIT_github_org",
    repo_url="https://github.com/org/my-repo",
    branch="main",
    wiki_name="my-repo_main",
    service_name=None,
    directory_name=None,
)

generate_docs(...) is an alias of generate_wiki(...).

This is async on the server — you'll be notified when the wiki is ready.

Low-Level Modules

For advanced usage or direct control over endpoints and payloads, you can use the individual modules:

adaptsapi.generate_docs

• post(endpoint, token, payload, timeout=30) — Wiki generate (connection_id, repo_url, branch, wiki_name, …).
• default_generate_docs_url() — Resolve the generate-docs URL from config, or None if unset.

adaptsapi.list_git_connections / adaptsapi.list_git_repos

• post(...) — List connections (empty body) or repos (connection_id).

adaptsapi.release_notes

• post(endpoint, token, payload, timeout=30) — Nested release-notes body; sets action to generate_release_notes.
• default_release_notes_url() — Resolve the release-notes URL from config, or None if unset.

adaptsapi.read_release_notes

• post_list_release_notes(endpoint, token, payload=None, timeout=30) — List notes; body may include wiki_id, limit, next_token (all optional).
• post_get_release_note(endpoint, token, payload, timeout=30) — Fetch one note; body requires wiki_id and release_id.
• default_list_release_notes_url(), default_get_release_note_url() — Resolve URLs from config or defaults.

adaptsapi.chat

• post_chat(endpoint, token, payload, timeout=30) — Start a chat. Returns thread_id + created_on for polling.
• post_chat_status(endpoint, token, payload, timeout=30) — Poll for chat response by thread_id + created_on.
• post_chat_enabled_wikis(endpoint, token, timeout=30) — List wikis available for chat. No payload needed.

adaptsapi.get_list_of_all_wikis

• post(endpoint, token, timeout=30) — List all wiki generation requests for your org. No payload needed.

adaptsapi.config

• load_token() — Resolve API key: ADAPTS_API_TOKEN / ADAPTS_API_KEY env var → config.json token → interactive prompt.
• load_api_base_url() — Resolve base URL: ADAPTS_API_BASE_URL env var → config.json base_url / api_base_url → default prod.
• load_default_endpoint() — Full generate-docs URL from config (metadata block → legacy endpoint → base + path).
• load_release_notes_endpoint() — Full release-notes URL from config.
• load_chat_url(), load_chat_status_url(), load_chat_enabled_wikis_url(), load_get_list_of_all_wikis_url(), load_list_release_notes_url(), load_get_release_note_url() — Endpoint URLs from config or defaults.

CLI Reference

adaptsapi (--chat | --chat-status | --chat-enabled-wikis | --list-wikis | --list-git-connections | --list-git-repos | --list-release-notes | --get-release-note | --generatedoc | --releasenotes) [OPTIONS]

Generate Wiki Payload Structure

For --generatedoc:

{
  "connection_id": "GIT_github_org",
  "repo_url": "https://github.com/org/my-repo",
  "branch": "main",
  "wiki_name": "my-repo_main"
}

Generate Release Notes Payload Structure

For --releasenotes (nested body):

{
  "email_address": "user@example.com",
  "user_name": "github_username",
  "repo_object": {
    "repository_name": "my-repo",
    "source": "github",
    "repository_url": "https://github.com/user/my-repo",
    "branch": "main",
    "size": "12345",
    "language": "python",
    "is_private": false,
    "git_provider_type": "github",
    "refresh_token": "github_token_here"
  }
}

Configuration

config.json

Place in the current working directory. Common keys:

Override the host with ADAPTS_API_BASE_URL environment variable.

Example (paths + base):

{
  "token": "your-api-token-here",
  "base_url": "https://prod.api.adapts.ai",
  "generate_wiki_docs_metadata": { "path": "/generate_wiki_docs" },
  "generate_release_notes_metadata": { "path": "/generate_release_notes" },
  "list_release_notes_metadata": { "path": "/list_release_notes" },
  "get_release_note_metadata": { "path": "/get_release_note" }
}

Example (legacy single endpoint):

{
  "token": "your-api-token-here",
  "endpoint": "https://prod.api.adapts.ai/generate_wiki_docs"
}

Environment Variables

Error Handling

The library provides comprehensive error handling:

• AdaptsAPIError: Raised when the API returns a non-2xx response (has .status_code and .body)
• PayloadValidationError: Raised when payload validation fails (missing fields, wrong types)
• ConfigError: Raised when no token can be found or loaded
• TimeoutError: Raised when .chat() polling exceeds poll_timeout
• requests.RequestException: Raised on network failures

Common Error Scenarios

• Missing token: CLI prompts for interactive token input and saves to config.json
• Invalid JSON: Shows JSON parsing errors with details
• API errors: Displays HTTP status codes and error messages
• Payload validation: Shows specific validation failures with field names

GitHub Actions Integration

Automate wiki generation on every merged PR:

name: Generate Wiki Docs

on:
  pull_request:
    branches: [ main ]
    types: [ closed ]

jobs:
  generate-docs:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install adaptsapi
      - name: Generate documentation
        env:
          ADAPTS_API_KEY: ${{ secrets.ADAPTS_API_KEY }}
          ADAPTS_CONNECTION_ID: ${{ secrets.ADAPTS_CONNECTION_ID }}
        run: |
          python -c "
          import os
          from adaptsapi import AdaptsClient
          client = AdaptsClient()
          client.generate_wiki(
              connection_id=os.environ['ADAPTS_CONNECTION_ID'],
              repo_url='${{ github.event.repository.html_url }}',
              branch='main',
              wiki_name='${{ github.event.repository.name }}_main',
          )
          print('Documentation generation submitted')
          "

Setting up GitHub Secrets

1. Go to your repository on GitHub
2. Click Settings → Secrets and variables → Actions
3. Click New repository secret
4. Add ADAPTS_API_KEY with your API token value

Changelog

v0.2.2

• Wiki generate: list_git_connections(), list_git_repos(), generate_wiki() / generate_docs() with connection_id, repo_url, branch, wiki_name (+ optional fields)
• Release notes generate stays nested

v0.2.1

• Read release notes: list_release_notes(), get_release_note() on AdaptsClient
• CLI: --list-release-notes, --get-release-note
• Low-level: adaptsapi.read_release_notes

v0.2.0

• AdaptsClient — high-level client (chat, chat_async, poll_chat_status, list_chat_enabled_wikis, list_all_wikis, generate_docs)
• Chat API and CLI flags: --chat, --chat-status, --chat-enabled-wikis, --list-wikis

Earlier

• Generate-docs / generate-release-notes clients and CLI (--generatedoc, --releasenotes)

Support

• Email: dev@adapts.ai
• Issues: GitHub Issues