Imported from swipe-YC21/partner-api-docs (AGENTS.md). Install upstream with npx skills add swipe-YC21/partner-api-docs. Copyright stays with the author.

Swipe Partner API Docs — Agent Guide

Mintlify documentation for the Swipe Partner API, published at https://developers.getswipe.in. Pushing to main auto-deploys via the Mintlify GitHub App — treat every push as a production deploy.

Golden rules

1. Do not commit or push unless explicitly asked. Make changes, verify locally, and leave the working tree for review.
2. Never hand-edit api-reference/openapi.json. It is generated — see "Spec pipeline" below. Content fixes belong in the backend or the overlay.
3. Verify locally before finishing: npx --yes mint@latest broken-links must pass, docs.json must be valid JSON, and for content changes run the dev server (npx --yes mint@latest dev, port 3000; a preview config exists in .claude/launch.json) and check the changed pages render.
4. Every .mdx file is publicly served even if it's not in the nav — never leave orphaned pages. When deleting or renaming a page, add a redirect in docs.json.

Repo map

Spec pipeline (important)

The backend (vectorx-automated-erp repo, flask_restx code in services/api/src/partner/) serves Swagger 2.0 at https://app.getswipe.in/api/partner/swagger.json (fetch with a non-default User-Agent; plain urllib gets a Cloudflare 403). To update the docs spec:

python3 .claude/skills/sync-openapi/scripts/convert.py

This converts to OpenAPI 3.0.1 and applies spec-overlay.json:

• exclude_path_prefixes — /v2/expense is intentionally undocumented (live routes, hidden with doc=False in the backend too).
• operations — endpoint descriptions, applied only when the backend operation has none. The long-term home for these is the backend docstring body (first line = summary, rest = description); each one moved there can be deleted from the overlay.
• The converter also garbage-collects unreferenced schemas and reports added/removed paths. New paths need an MDX page, a nav entry, and a changelog entry; removed paths need page deletion + a redirect.
• Postman: the spec is mirrored to Postman's Spec Hub AND the public "Run in Postman" collection is regenerated from it. A push to main touching openapi.json triggers .github/workflows/postman-sync.yml (needs the POSTMAN_API_KEY repo secret), which runs push_postman.py --update-collection. The collection is purely generated — never hand-edit it in Postman, every sync overwrites it. Workspace/spec ids live in scripts/postman.json — never store the API key in the repo.

Backend gotcha: flask_restx registers swagger models in a global registry keyed by name. Two models with the same name silently overwrite each other and corrupt the generated schema (this happened; all names were de-duplicated on 2026-08-26 — v1 copies got a V1 suffix, vendor copies a Vendor prefix). When adding backend models, keep names globally unique.

Content conventions

• Every page needs frontmatter: title, description, and icon (FontAwesome name). Descriptions feed SEO and llms.txt.
• Internal links are root-relative (/api-reference/...), never absolute https://developers.getswipe.in/... — the link checker only validates relative links. CI runs it on every PR (.github/workflows/broken-links.yml).
• Guide pages follow a template: what the resource is → lifecycle (Mermaid where useful) → one minimal real payload in a <CodeGroup> (cURL / Python / JavaScript) → gotchas as callouts → dashboard screenshot in <Frame> → <CardGroup> of endpoint links.
• Any API-visible change gets an entry in api-reference/change-log.mdx (dated <Update> component, text not screenshots).
• Sidebar group names have no version suffix ("Documents", not "Document V2").

API facts (verified — don't contradict these)

• Base URL: https://app.getswipe.in/api/partner; auth is Authorization: Bearer <API key>.
• API keys are company-scoped. Docs recommend creating a separate test company for experimentation (guide: https://community.getswipe.in/t/how-to-add-new-company-on-web/1191).
• Rate limit: 1 request/second (confirmed by the team). The status code returned when exceeded is unconfirmed — don't invent a 429.
• All dates are DD-MM-YYYY. Responses use the envelope {success, message, error_code, errors, data}; business errors → HTTP 400, auth → 401, unexpected → 500.
• Documents are addressed by the hash_id returned at creation. Subscriptions are created via POST /v2/doc with document_type=subscription — there is no separate create endpoint.
• The only MCP server documented here is the docs one, https://developers.getswipe.in/mcp (Mintlify-hosted docs search, free, unauthenticated), on /build-with-ai.
• Do not document https://app.getswipe.in/api/mcp/sse in this repo. That is the Swipe AI assistant over MCP, a separate end-user product: different Flask blueprint (/mcp vs /partner), and it authenticates with an OAuth PKCE plus mobile-OTP JWT rather than a Partner API key. A Partner API key returns 401 against it. It is account-scoped to one logged-in person for 30 days, so a partner backend serving many companies cannot use it at all. It was documented here once and removed; its home is the product/help docs. (Its tools reuse src/partner/v2/* business logic internally, which is why it looks like a Partner API surface in the backend code. It is not one.)
• The site is on Mintlify's free tier: the paid Assistant ("Ask AI") and personalization (playground key-prefill) are not available — don't reference them as existing features.

Known open items

• The webhook response-timeout value (10s) and the currency-table corrections (Zimbabwe ZWL, Bosnia BAM, Palestine) still need backend confirmation.
• Analytics integration in docs.json is pending a GA4/PostHog ID.
• Expense endpoints stay hidden until the team decides to publish them; when that happens, remove doc=False in the backend, drop the overlay exclusion, regenerate, and build an "Expenses" group with pages + nav + changelog.