Talk to the Spaaza API

This skill allows an AI agent to "talk" to the Spaaza API on your behalf using natural language instructions.

It can:

• authenticate an admin user session,
• store issued session information in the user's home directory for reuse between sessions,
• determine the admin user's permitted chains after login before chain-scoped API work,
• retrieve information about chains, campaigns, users, vouchers, and baskets,
• carry out approved API changes,
• build request shortlists and request payloads from the Spaaza Postman collection, the Resources API schema, and the documentation site,
• report results clearly.

This is similar to common Spaaza Console tasks, but text-based.

Security and credentials

This skill is designed to be security-first:

• credentials should be requested only when required,
• credentials and OTP/session data should be used only for the active session,
• staging should be used by default unless production is explicitly requested.

By default, credentials are entered per session, but issued session information may be stored in the user's home directory for reuse between sessions.

This cache should contain only issued session data such as session key, session user ID, environment, and expiry metadata. Usernames, passwords, and OTP codes should never be stored.

Environments and documentation

• Staging (test01): https://apistage0.spaaza.com
• Production (prod): https://api0.spaaza.com

Deployment flow:

• develop -> test01
• master -> prod

Documentation:

• Staging docs: https://docs-test01.spaaza.com
• Production docs: https://docs.spaaza.com

Agents should read the login documentation before creating login requests. Agents should also read the relevant endpoint documentation before consuming other API endpoints. If a page is missing on one docs host, agents should check the equivalent page on the other docs host before guessing request details.

Postman collection

Spaaza maintains a public, cloneable Postman collection at:

• https://github.com/Spaaza/SPAAZA.postman

Used side-by-side with this skill, the collection helps an agent:

• discover available requests and endpoint groupings,
• reuse prepared headers, parameters, and body examples,
• draft API requests more quickly before confirming behavior against the documentation site,
• assemble a practical endpoint catalogue for the current task.

For resource-oriented work, agents should also use the Resources API schema endpoint:

• GET /resources/schema

The documentation site remains the primary public reference for endpoint behavior and authentication requirements.

Using the collection side-by-side with this skill

Recommended workflow:

1. Install this skill in your AI agent.
2. Tell the agent whether you already have a local clone of https://github.com/Spaaza/SPAAZA.postman.
3. If you do, provide that path so the agent can inspect the collection locally.
4. If you do not, let the agent use the public repository or clone it into a user-approved local directory.
5. Let the agent combine the collection, the documentation site, and the Resources API schema to form and validate requests.

If your agent supports user-local memory or config files, you can allow it to remember the clone path for future sessions. That remembered path should contain only the collection location, never credentials or session keys.

Optional session reuse between agent sessions

This skill supports faster follow-up sessions by reusing active Spaaza session information from a user-local cache.

Recommended behavior:

1. At the start of a session, first ask whether the user already has an active session or has used this skill before for the target environment.
2. Recover as much context as possible from cached session data and remembered Postman metadata before asking further questions.
3. Store cached session data only in a user-local directory outside any repository.
4. Keep separate cache files per environment such as test01 and prod.
5. Use restrictive file permissions where possible.
6. If a matching unexpired cached session exists, reuse it before asking for login details.
7. If no cached session exists, or it has expired, ask for the login information and then write or replace the environment-specific cache file after a successful login.

The cache should contain only the issued session values and related metadata. It should never contain usernames, passwords, or OTP codes.

Request handling and verification

When using this skill, agents should:

1. Include X-Spaaza-API-version on requests.
2. Default to X-Spaaza-API-version: 1.6.3 unless the relevant endpoint documentation says a different version should be used.
3. Include a User-Agent header when possible.
4. Use the Postman collection and the documentation site to shortlist likely endpoints before making non-trivial requests.
5. After login, retrieve the admin user's permitted chains before chain-specific reads or mutations.
6. Verify changes with a follow-up get-* request where a matching read endpoint exists.
7. Restart the login flow if an OTP expires.

For multi-step authenticated work, using a JSON-aware wrapper around curl or an equivalent method can reduce quoting and parsing errors.

Endpoint catalogue (documented endpoints)

These endpoints are amongst the many already documented in this site and are useful for AI-assisted workflows. The Postman collection can be used to expand this shortlist for the task at hand before checking the relevant documentation pages.

Endpoint	Typical use	Documentation
POST /auth/login	Start login flow, including admin 2FA initiation	User login
POST /auth/session	Complete admin 2FA and create session	Create a user session when provided with valid credentials
GET /internal/get-campaigns	List campaigns for a chain	Getting campaigns
GET /internal/get-campaign	Get details for one campaign	Get a campaign
POST /auth/get-basket-price	Evaluate basket and campaign effects	Get basket adjustments
POST /auth/add-basket	Add/finalise basket transactions	Adding baskets
GET /internal/get-user	Retrieve user profile and status	Get user
GET /internal/get-businesses	Retrieve businesses for a chain	Getting all businesses
GET /internal/get-vouchers	Inspect voucher state and eligibility	Get vouchers

Skill file

• Repository file:
  • spaaza-api-live-access/SKILL.md