# Blitera API Agent

Use this skill when an agent needs to call, document, or reason about the Blitera API.

## Mandatory Reading

Before making API calls, read:

1. `docs/API_AGENT_GUIDE.md`
2. `docs/api/blitera-api-manifest.json`
3. The relevant script in `scripts/api/`

When operating from the published documentation site, use:

1. `/api-agent/API_AGENT_GUIDE.md`
2. `/api-agent/blitera-api-manifest.json`
3. `/api-agent/skills/blitera-api-agent/SKILL.md`
4. `/api-agent/scripts/api/`

## Operating Rules

- Use `BLITERA_BASE_URL` and `BLITERA_API_KEY` environment variables.
- Never hardcode or echo API keys.
- Never put `account_id` in a request body, query string, generated example, or script.
- Never call session-only endpoints with `X-API-Key`.
- Treat `403` as an authorization boundary. Do not enumerate workspace IDs or retry with guessed scopes.
- Ask for explicit operator confirmation before destructive or broad write actions.
- Prefer the existing PowerShell and Bash scripts over inventing ad hoc commands.

## Endpoint Selection

- For public link access history, use `/api/links/audit/log` or `/api/links/audit/export` with `audit:read`.
- For API key activity, use `/api/keys/audit/log` or `/api/keys/audit/export` only from an authenticated owner session.
- For assets, match the endpoint to the resource scope: `links:*`, `files:*`, or `collections:*`, including dedicated `*:delete` scopes for destructive operations.
- For workspace requests, require `BLITERA_WORKSPACE_ID` from a trusted operator or configuration source.

## Safe Defaults

- Prefer read-only requests.
- Use small limits such as `20` or `50`.
- Use explicit date ranges for audit exports.
- Save exports to local working files unless the operator names a destination.

## Refusal Conditions

Refuse or stop when asked to:

- Bypass scopes, workspace allowlists, CSRF, or session-only boundaries.
- Exfiltrate API keys, session cookies, encrypted file contents, or private tenant data.
- Guess workspace IDs or account IDs.
- Run destructive operations without explicit confirmation.