Client API

The Client API is a local service inside the app for advanced automation. It is not the public cloud API and should not be exposed to untrusted networks.

Typical Uses

Use the local API when you want a trusted script or local tool to:

• trigger deck sync;
• list cloud or local decks;
• create a deck;
• fetch a deck from cloud;
• update deck metadata;
• delete a local deck;
• list categories;
• create, update, search, or delete cards;
• upload or delete deck resources;
• integrate Cardary with a personal workflow.

Authentication

Protected endpoints require the app’s login state and a local secret through either:

• the X-API-SECRET header; or
• the secret query parameter.

Treat the secret like a credential. Do not paste it into public logs, browser history, shared scripts, or remote services.

Endpoint Groups

The app includes endpoint groups for:

Group	Purpose
Authentication	Check login and local API access state.
Sync	Trigger or inspect deck sync.
Decks	List, create, fetch, update, and delete decks.
Categories	Read deck category structure.
Cards	Search, create, update, and delete card content.
Resources	Upload and delete media or files used by cards.

Exact payload shapes can change with app versions. Check the app implementation when building a strict integration.

Safety Rules

• Use the API only on trusted machines.
• Do not bind it to public networks.
• Do not share the local secret.
• Test against a small deck first.
• Sync before and after large automated changes.
• Back up or export important decks before bulk updates.
• Avoid concurrent edits from the UI and a script unless you understand the sync behavior.

Automation Patterns

Good candidates:

• create a deck from a local data pipeline;
• update cards from a reviewed CSV export;
• attach generated images or audio;
• trigger sync after a controlled import;
• search cards for local quality checks.

Risky candidates:

• deleting large card sets without a backup;
• rewriting fields across a deck without preview;
• uploading unreviewed AI output;
• running scripts while another device edits the same deck;
• exposing the API through a remote server.

Troubleshooting

Problem	What to check
Request is unauthorized	Login state and X-API-SECRET.
Deck cannot be edited	Deck ownership, read-only state, and deck type compatibility.
Resource upload fails	Plus attachment limits, file path, size, and network.
Sync does not update another device	Run sync on both devices and wait for resources.
Payload error	Compare your request with the current app implementation.

Related: Account & Sync and Import Cards.