# Zaparoo Integration Reference

## Public sources

- Core API: <https://zaparoo.org/docs/core/api/>
- Core methods: <https://zaparoo.org/docs/core/api/methods/>
- Core notifications: <https://zaparoo.org/docs/core/api/notifications/>
- Pairing/encryption: <https://zaparoo.org/docs/core/api/encryption/>
- Online User API: <https://developers.zaparoo.com/openapi-user.yaml>
- Core development source: <https://github.com/ZaparooProject/zaparoo-core>

## Selection

| Need | Interface |
| --- | --- |
| Current device state or control | Core API |
| Reader/NFC interaction | Core API |
| Live media events | Core notifications |
| Remote account history | Online User API |
| Cards/decks linked to account | Online User API |
| Cloud backup snapshot files | Online User API |
| Build, deploy, package application | Target repository tooling |

## Core integration checklist

- Target explicit versioned endpoint.
- Pair remote clients when encryption is required.
- Bound connect and request timeouts.
- Correlate JSON-RPC IDs and handle protocol errors.
- Reconnect notification streams with backoff.
- Resynchronize authoritative state after reconnect.
- Treat API as pre-v1 until public Core contract changes.
- Ask before live mutations.

## User API integration checklist

- Fixed official HTTPS origin.
- Bearer User API key with least-required scope.
- No key in URL, command arguments, logs, or agent context.
- Cursor pagination with loop protection.
- `Retry-After` handling.
- ETag and minimum interval for active-session polling.
- Explicit destination and SHA-256 verification for backup files.
- Private data disclosure and retention appropriate to task.

## Agent verification loop

1. Reproduce request through first-class CLI command.
2. Capture sanitized structured response or failure classification.
3. Implement equivalent behavior in target repository.
4. Run local tests or mock Core.
5. Deploy using repository instructions.
6. Compare live behavior through CLI.

Do not turn a successful CLI experiment into undocumented API contract. Confirm behavior in public specification before publishing third-party integration guidance.