# Learning unfamiliar APIs

Use this procedure inside Learn Mode for HTTP, RPC, GraphQL, streaming, webhook, job, CLI-backed, or tool-call APIs.

## Start with contracts

Inspect OpenAPI/AsyncAPI/GraphQL schemas, protobufs, route registrations, SDK types, examples, mocks, server validators, authentication middleware, migrations, and clients. Treat examples as hypotheses until observed.

Build an endpoint or operation model containing:

- method/operation and normalized path or tool name;
- authentication, role, tenant, ownership, scopes, and headers;
- request fields, types, formats, enums, defaults, nullability, limits, and cross-field rules;
- response/status variants, error envelope, headers, pagination/cursors, versioning, and rate limits;
- idempotency, retry, concurrency, ordering, caching, polling, cancellation, streaming, and eventual consistency;
- external effects, notifications, billing, data retention, audit, cleanup, and rollback.

Record request and response **shapes**, redacted identifiers, and evidence references—not credentials, tokens, cookies, raw PII, or full sensitive bodies.

## Safe probe ladder

1. Read specifications and source contracts.
2. Use documented discovery/schema mechanisms.
3. Run bounded safe reads against a local or authorized test environment.
4. Probe one valid request, then missing/null, wrong type/format, exact boundaries, unknown fields, unsupported version/content type, and conditional combinations.
5. Check authorization with synthetic identities only when allowed.
6. Check pagination end conditions, retries, cancellation, timeouts, idempotency, concurrency, and eventual consistency with bounded volume.
7. Exercise writes only in a sandbox with synthetic records, explicit authorization, a known idempotency key, and verified cleanup.

Do not assume `OPTIONS`, `HEAD`, GraphQL introspection, health endpoints, or dry-run parameters are harmless; confirm the implementation or documented contract first.

For webhooks and callbacks, learn signature verification, replay windows, ordering, duplication, retry schedule, dead-letter behavior, and redaction without sending to a real customer endpoint.

For asynchronous jobs and streams, observe accepted/queued/running/succeeded/failed/canceled/expired states, reconnect/resume semantics, terminal conditions, partial output, backpressure, and cleanup.

Stop when safe reads cannot distinguish behavior, mutation or load authorization is missing, the target appears production/shared, or the next probe could expose another tenant’s data.

