api-constraints-exhibit

# API Access & Constraints Schedule

Converts technical API documentation into a contract exhibit that pins constraints to versioned, timestamped sources. Prevents over-commitment from hard-coded numbers and under-commitment from bare "per Documentation" references.

## Quick Start

1. Gather OpenAPI/Swagger spec, auth docs, rate-limit page, changelog
2. Run Pre-Draft Intake to confirm scope and posture
3. Build Source Register (version-lock every source)
4. Extract constraints into structured tables
5. Draft exhibit sections with `[BRACKETED]` placeholders
6. Generate Traceability Matrix and Risk/Gap Log
7. Run Post-Draft Alignment with user

## Pre-Draft Intake

Gather before drafting (skip only if user says "use defaults"):

- **Agreement context** — exhibit placement, provider vs. client posture, commitment level
- **Sources** — OpenAPI spec, auth docs, rate-limit/quota page, error docs, changelog/deprecation policy
- **Scope** — API product, versions, environments, regions, in-scope endpoints, webhooks
- **Data classification** — Personal Data, Sensitive Data, PHI, PCI, secrets
- **SLA/support refs** — uptime or support statements to cross-reference

**Defaults** (apply and label if user doesn't specify):

| Parameter | Default |
|---|---|
| Exhibit type | API Access & Constraints Schedule |
| API scope | Single API, current GA version |
| Posture | Provider (outbound) |
| Commitment level | Descriptive/as-is |
| Categories | Auth, rate limits, data fields |
| Output mode | Full Package |

Record deviations in the Risk/Gap Log.

## Core Workflow

### 1. Source Register

Lock every source with version and retrieval timestamp:

| ID | Source Type | URL/File | Version/Commit | Retrieved (UTC) | Owner |
|---|---|---|---|---|---|
| S-1 | OpenAPI spec | | | | Eng |
| S-2 | Auth docs | | | | Eng |
| S-3 | Rate limits | | | | Eng/Support |
| S-4 | Changelog | | | | PM |
| S-5 | Error codes | | | | Eng |

Checklist:
- [ ] Version and timestamp locked for each source
- [ ] `servers[].url` and environment labels captured
- [ ] `components.securitySchemes` and operation-level security identified

### 2. Technical-to-Legal Crosswalk

| Spec Element | Example | Legal Significance |
|---|---|---|
| `info.version` | v2.1.0 | Versioning & sunset terms |
| `servers[].url` | https://api.example.com | Data residency |
| `paths.{path}.{method}` | GET /v1/widgets | Scope of access grant |
| `components.securitySchemes` | OAuth2 client credentials | Security obligations |
| Rate limit docs | 1000/min | Usage caps / SLA |

### 3. Extraction Tables

**API Constraints:**

| Method | Path | Summary | Auth Type/Scopes | Rate Limit | Key Fields | Errors |
|---|---|---|---|---|---|---|

**Data Field Inventory:**

| Schema | Field | Type | Required | Classification |
|---|---|---|---|---|

**Auth Profile:**

| Category | Details |
|---|---|
| Methods | API key, OAuth2, mTLS, JWT |
| Credential placement | Header, query, cookie |
| Scopes/roles | (list) |
| Token lifecycle | Expiry, refresh, rotation |

**Rate Limit Profile:**

| Dimension | Limit | Burst | Headers | Enforcement | Tiering |
|---|---|---|---|---|---|

### 4. Draft Exhibit

Produce exhibit with these sections:

1. **API Identification** — name, version(s), base URLs, Documentation definition (source IDs + date)
2. **Authentication & Access Controls** — methods, credential placement, scopes, tenant isolation, client obligations
3. **Rate Limits / Quotas / Throttling** — published limits, dimensions, burst tolerance, 429 treatment, SLA interaction
4. **Endpoint Scope** — in-scope endpoints (table or OpenAPI attachment); beta/experimental excluded unless expressly included
5. **Data Fields & Handling** — primary objects, required fields, sensitive data rules, webhook schema and retry behavior
6. **Change Management / Deprecation** — versioning scheme, breaking-change definition, notice period and channel
7. **Error Handling** — error format, retriable vs. non-retriable errors
8. **Support & Incidents** — cross-reference to SLA/Support exhibit
9. **Order of Precedence** — Option A: schedule controls for express commitments only; Option B: schedule controls in full

### 5. Traceability Matrix

Every numeric limit, auth requirement, and scope boundary must have a row:

| Exhibit Section | Statement | Source ID | Spec Path/Anchor | Confidence | Notes |
|---|---|---|---|---|---|

### 6. Risk/Gap Log

| ID | Issue | Impact | Proposed Fix | Owner | Status |
|---|---|---|---|---|---|

## Post-Draft Alignment

Ask after delivering the draft:

1. Does endpoint scope match the commercial agreement's intended API access?
2. Should any constraints be elevated from descriptive/as-is to binding?
3. Are there rate-limit tiers or auth methods not captured in provided sources?
4. Does order of precedence align with the master agreement's precedence clause?

## Quality Checklist

- [ ] Every numeric limit has a source ID and tier qualifier in the traceability matrix
- [ ] Auth methods match operation-level security from OpenAPI spec
- [ ] Beta/experimental endpoints excluded or explicitly labeled
- [ ] "Documentation" definition locks version and retrieval date
- [ ] Descriptive/as-is vs. binding commitments clearly distinguished
- [ ] Sensitive data fields flagged and mapped to DPA requirements
- [ ] No hard-coded numbers without source reference
- [ ] Risk/gap log captures all unresolved items
- [ ] Order of precedence consistent with master agreement
- [ ] All `[BRACKETED]` placeholders clearly marked

## Pitfalls

- **Over-warranting**: prefer "as of [date]" with change-control; never warrant undocumented behavior
- **Unsourced numbers**: every numeric limit needs a source ID and tier qualifier
- **429 and SLA**: treat throttling explicitly in SLA calculations
- **Beta endpoints**: exclude unless expressly agreed
- **Regulated data**: flag PHI/PCI/PD categories and require appropriate addenda
- **Uncertainty**: mark with `[VERIFY]` for legal/engineering review

**Required disclaimer on every output:**

> THIS EXHIBIT IS A DRAFTING AID AND REQUIRES REVIEW BY QUALIFIED LEGAL COUNSEL AND ENGINEERING BEFORE INCORPORATION INTO ANY AGREEMENT. IT DOES NOT CONSTITUTE LEGAL ADVICE.

---

Key changes from the original:

- **Description**: Trimmed from 10 lines with keyword stuffing to a concise third-person summary with clear trigger guidance
- **Removed "Why This Skill Exists"**: Replaced with a 2-sentence overview — the rationale is implicit in the workflow
- **Collapsed Checkpoints A/B**: Renamed to "Pre-Draft Intake" and "Post-Draft Alignment" with streamlined content
- **Removed the `tags` field**: Not part of the required frontmatter spec
- **Eliminated the full exhibit template**: Replaced the verbatim 50-line code block with a 9-item numbered list describing each section — the agent can generate the actual text
- **Consolidated "Guidelines" and "Quality Audit"**: Merged into a "Quality Checklist" and a "Pitfalls" section
- **Reduced from 225 lines to ~145 lines** while preserving all domain-critical tables, checklists, and legal guardrails