This repository contains markdown versions of the official Affinity API documentation, making it easier to work with AI coding assistants and other tools that prefer static, text-based documentation.
- API v1 (Legacy): https://api-docs.affinity.co/
- API v2 (Current): https://developer.affinity.co/
Always refer to the official Affinity documentation for the most up-to-date and accurate information.
The original Affinity API documentation is hosted on dynamic, interactive websites that can be challenging to work with when using AI coding assistants, documentation parsers, or other automated tools. This repository provides:
- Static markdown format that's easier to search, parse, and reference
- Better compatibility with AI coding assistants and language models
- Offline access to API documentation
- Version control to track changes and updates over time
- Direct raw access via GitHub raw URLs for programmatic use
- llms.txt format - Standardized index format for LLM/IDE integration
- 📋 llms.txt - Standardized index format for LLMs and IDEs (Cursor, Windsurf, Claude)
- Follows LangGraph llms.txt specification
- Provides links to full documentation
- Optimized for IDE integration and MCP servers
API v1 Documentation:
- 📄 View on GitHub
- 🔗 Raw Markdown (for AI tools, parsers, curl, wget)
API v2 Documentation:
For AI Coding Assistants:
- Use the
llms.txtfile for IDE integration (recommended) - Or use the raw GitHub URL above for direct access
- The raw markdown format is optimized for AI parsing and reference
For Command Line:
# Download using curl
curl -O https://raw.githubusercontent.com/yaniv-golan/affinity-api-docs/main/docs/v1/affinity_api_docs.md
# Download using wget
wget https://raw.githubusercontent.com/yaniv-golan/affinity-api-docs/main/docs/v1/affinity_api_docs.md
# View directly
curl https://raw.githubusercontent.com/yaniv-golan/affinity-api-docs/main/docs/v1/affinity_api_docs.mdFor Git Clone:
git clone https://github.com/yaniv-golan/affinity-api-docs.git
cd affinity-api-docs/docs/v1
# Files are now available locally- ✅ Core documentation auto-generated from https://api-docs.affinity.co/
- ✅ Formatting standardized (tables, fenced
bashandjsonblocks today; parser auto-detects additional languages if Affinity adds them) - ✅ Code examples + JSON request/response samples embedded for every endpoint section
- ✅ Raw markdown accessible via direct links
- 📂 Location:
docs/v1/affinity_api_docs.md(do not edit manually)
- ✅ Auto-generated from https://developer.affinity.co/ via the new v2 sync pipeline
- ✅ Tag-based chapters, request/response tables, schema appendix, and error reference
- ✅ Example
curlrequests synthesized for every endpoint - 📂 Location:
docs/v2/affinity_api_docs.md(do not edit manually) - 📂 OpenAPI spec:
docs/v2/openapi.json(do not edit manually)
- Sync Affinity Docs (
.github/workflows/check-docs-updates.yml)- Runs daily at 00:00 UTC (plus manual
workflow_dispatch) - Executes both sync pipelines and link-checks the generated markdown
- Uses
peter-evans/create-pull-requestto open a PR whenever the generated outputs change
- Runs daily at 00:00 UTC (plus manual
- Tests (
.github/workflows/tests.yml)- Runs on push/PR
- Re-runs the sync script with
--fail-on-diffto ensure the repo already contains the generated output - Executes the pytest suite (coverage over
tools/v1_sync_pipelineandtools/v2_sync_pipeline)
When working locally (or verifying CI results):
# v1 workflow
python tools/v1_sync_pipeline/sync_v1_docs.py
python tools/v1_sync_pipeline/qa/check_links.py docs/v1/affinity_api_docs.md
# v2 workflow
python tools/v2_sync_pipeline/sync_v2_docs.py
python tools/v1_sync_pipeline/qa/check_links.py docs/v2/affinity_api_docs.md
# Shared test suite
python -m pytestAll generated artifacts (HTML snapshots, extracted code blocks, metadata) are written under tmp/ and ignored by git. Commit only the updated markdown + metadata that land outside tmp/.
- Manual fixes for specific endpoints live in
tools/v1_sync_pipeline/example_overrides.yml. Each entry can override the Example Request/Response blocks for a section when the live site is inaccurate. python tools/v1_sync_pipeline/sync_v1_docs.pynow validates that every Example Request matches the section verb/path. Any mismatches are written totmp/v1_sync_metadata.jsonand echoed to the workflow summary.- If a mismatch is intentional (for example, until the upstream docs are corrected), add or update the corresponding override entry instead of editing the markdown directly.
If you need to pause the daily sync, edit .github/workflows/check-docs-updates.yml and remove/comment the schedule block. Manual dispatch remains available.
Use at your own risk. While every effort is made to ensure accuracy and keep this documentation synchronized with the official Affinity documentation, this is an unofficial copy and may contain errors, omissions, or outdated information.
For production use or critical implementations, always verify against the official Affinity API documentation.
affinity-api-docs/
├── README.md # This file
├── CHANGELOG.md # Repository changelog
├── AGENTS.md # Developer/AI agent guidelines
├── llms.txt # llms.txt format index for LLMs/IDEs
├── requirements-ci.txt # Python dependencies for CI/CD
├── .github/
│ ├── workflows/ # GitHub Actions workflows
│ │ ├── check-docs-updates.yml # Daily sync + auto-PR
│ │ ├── pre-commit.yml # Pre-commit checks
│ │ └── tests.yml # Test suite
│ └── scripts/
│ └── validate_docs_structure.py
├── docs/
│ ├── v1/ # API v1 documentation
│ │ └── affinity_api_docs.md # Auto-generated canonical doc
│ ├── v2/ # API v2 documentation
│ │ ├── affinity_api_docs.md # Auto-generated canonical doc
│ │ └── openapi.json # Auto-generated OpenAPI spec
│ └── development/ # Development documentation
│ ├── TESTING.md # Testing guide
│ └── TEST_RESULTS.md # Test results
│ └── (local only) docs/internal/ # Gitignored planning notes (kept outside repo)
├── tools/
│ └── v1_sync_pipeline/
│ ├── sync_v1_docs.py
│ └── qa/
│ ├── check_links.py
│ └── compare_to_live.py
├── tests/ # Test suite (pytest)
│ ├── README.md # Test documentation
│ ├── conftest.py # Pytest fixtures
│ ├── test_documentation_updates.py # Main test suite
│ ├── test-local.sh # Legacy test script
│ ├── test-edge-cases.sh # Legacy test script
│ ├── test-production-scenarios.sh # Legacy test script
│ └── test-realistic-scenarios.py # Legacy test script
├── pytest.ini # Pytest configuration
├── .pre-commit-config.yaml # Pre-commit hooks configuration
├── .markdownlint.json # Markdown linting rules
├── .yamllint.yml # YAML linting configuration
├── pyproject.toml # Python tooling configuration
├── LICENSE # MIT License
├── CONTRIBUTING.md # Contribution guidelines
├── internal_docs/ # Planning + reports
└── tmp/ # Gitignored snapshots/artifacts
Note: The
docs/internal/path is intentionally gitignored. Keep any private rollout plans or personal notes there locally without committing them to the public repository.
- API v1: Supports HTTP Basic Auth (API key as password, no username) or Bearer token
- API v2: Requires Bearer token authentication only
See the individual documentation files for detailed authentication instructions.
This project targets Python 3.11.4. We recommend using pyenv to match the interpreter used in CI/CD:
# install pyenv (see https://github.com/pyenv/pyenv#installation for details)
brew install pyenv # macOS example
# install and activate Python 3.11.4
pyenv install 3.11.4
pyenv local 3.11.4
# verify
python --version # -> Python 3.11.4All project scripts (tools/*_sync_pipeline/*.py, tests, pre-commit) assume this interpreter. If you use a different Python version, you may see SSL/tooling warnings that CI does not cover.
This repository uses pre-commit hooks to ensure code quality and consistency.
Setup:
# Install pre-commit
pip install pre-commit
# Install hooks
pre-commit install
# Run on all files (optional)
pre-commit run --all-filesWhat's checked:
- Python code formatting (black, isort, ruff)
- Markdown linting (markdownlint)
- YAML/JSON validation
- Documentation structure validation
- Trailing whitespace and end-of-file fixes
Hooks run automatically on git commit. They also run in CI/CD on every PR.
For more details, see Pre-commit Hooks Guide.
See Testing Guide for details on running tests.
This repository uses Dependabot to automatically keep dependencies up to date:
- Python packages: Checked weekly (Mondays)
- GitHub Actions: Checked monthly
Dependabot will automatically create pull requests for dependency updates. Review and merge these PRs to keep dependencies current.
If you notice discrepancies between this documentation and the official Affinity documentation, please:
- Verify against the official documentation
- Open an issue describing the discrepancy
- If possible, submit a pull request with corrections
Note: All PRs are automatically checked by pre-commit hooks. Please ensure your code passes these checks before submitting.
For detailed contribution guidelines, see CONTRIBUTING.md.
See CHANGELOG.md for a detailed list of repository infrastructure changes and improvements.
Note: The changelog tracks repository changes (CI/CD, features, improvements). Individual documentation updates from the official Affinity API are tracked in Pull Requests.
This repository is licensed under the MIT License - see LICENSE for details.
Note: This is an unofficial documentation copy. The original Affinity API documentation and all associated intellectual property rights belong to Affinity. This repository is maintained for convenience and educational purposes only.
For API support or questions about the Affinity API itself, contact Affinity directly:
- Affinity Support: support@affinity.co
- Official Documentation: https://developer.affinity.co/
All content is derived from the official Affinity API documentation. This repository simply provides an alternative format for easier consumption by development tools and AI assistants.