# Prophit.ai ITMS Agent Starter Pack

Use this pack to give an AI agent a bounded introduction to the ITMS API. The current API reference at `/api-access/reference` and the schemas returned by ITMS are authoritative if this file and the running service ever differ.

## Connection variables

- `ITMS_BASE_URL`: the base URL for the approved sandbox or production environment
- `ITMS_API_KEY`: an ITMS API key with only the scopes the workflow needs
- `ITMS_CLIENT_REF`: required for service-provider calls that act in a taxpayer client context

Send the API key as `Authorization: Bearer <key>`. Never paste a real credential into a prompt, source file, transcript, or log.

## Safe first operation

Start with `GET /api/v1/config`. It is read-only and returns the effective environments, limits, scopes, tax-code registry, and webhook event names available to the authenticated key.

Then review `/api-access/coverage`, `/api-access/authentication`, `/api-access/errors`, and `/api-access/rate-limits` before choosing another endpoint.

## Authority policy

1. Begin in an approved sandbox with least-privilege credentials.
2. Treat missing jurisdiction coverage, a missing rule, a validation error, and an ambiguous client context as a stop condition.
3. Do not infer that a successful read or calculation authorizes a commit, filing, transmission, payment, refund, void, credential change, or other write.
4. Before every write, summarize the exact endpoint, tenant, environment, payload purpose, persistence effect, and expected result for human review.
5. Require explicit human approval immediately before any filing, transmission, payment, production credential change, or other consequential external action.
6. Preserve the request ID, warnings, coverage metadata, and returned evidence with the result.
7. Respect rate limits and idempotency behavior. Never retry an ambiguous write automatically.
8. Escalate rather than guess.

## Read-only connection check

```bash
curl "$ITMS_BASE_URL/api/v1/config" \
  -H "Authorization: Bearer $ITMS_API_KEY"
```

This verifies only that the credential can read configuration. It does not authorize tax calculations or downstream actions.

## Recommended agent output

For every proposed operation, return:

- environment and tenant context
- method and endpoint
- required scope
- whether the operation persists data
- facts supplied by the user or source system
- unresolved assumptions or missing inputs
- warnings and returned authority metadata
- the human decision required next