# WEIR — Full Documentation for LLMs

> WEIR is an identity rights platform. Individuals register their name, image, and likeness (NIL) as digital licenses. Third parties discover, purchase, and comply with these licenses via the WEIR API.

## Table of Contents

1. [Core Concepts](#core-concepts)
2. [License Types Reference](#license-types-reference)
3. [Mentions & Detection](#mentions--detection)
4. [Claims & Enforcement](#claims--enforcement)
5. [Identity Rights Reference](#identity-rights-reference)
6. [Discovery Protocol](#discovery-protocol)
7. [Authentication](#authentication)
8. [API Endpoints](#api-endpoints)
9. [Webhooks](#webhooks)
10. [Embed & Widgets](#embed--widgets)
11. [Rules for AI Agents](#rules-for-ai-agents)
12. [Links](#links)

---

## Core Concepts

### Identity Licenses

A license represents usage rights for a person's identity. Each license has:

- `external_id` — Public identifier (e.g., `lic_abc123`)
- `title` — Display title
- `status` — `draft`, `public`, or `archived`
- `license_type` — Category of usage rights (see License Types Reference below)
- `valid_until` — Expiration date (null = perpetual)
- `allow_embed` — Whether the license appears in public feeds

### Identity Metadata

Each license is linked to identity metadata containing:

- `stage_name` — Public display name
- `identity_type` — `person`, `character`, `brand`, or `group`
- `is_verified` — Whether identity has been verified
- Legal name is **never exposed** in public APIs.

### Mentions

A mention is a detected use of a licensed identity in content across the web. There are two types:

- **Name Mentions** — Content where the person's name explicitly appears (text detection)
- **Deep Mentions** — Content where the person's likeness was visually detected without their name explicitly appearing (requires biometric consent)

See [Mentions & Detection](#mentions--detection) for full details.

### Workgroups

Licenses support collaborative management through a team model:

- **Owner (Licensor)**: Full control over the license, can grant/revoke all permissions, transfer ownership
- **Manager (Trustee)**: Can manage team members, license settings, and day-to-day operations
- **Reviewer (Viewer)**: Read-only access to license data, mentions, and analytics

A single user can manage licenses for multiple different identities (agency model). This enables talent managers, attorneys, and agencies to operate across clients from a single account. Permissions are granted per-license, can have expiration dates, and all changes are audit-logged.

### Claims

When unlicensed use of an identity is detected, a formal claim can be filed. Claims are the enforcement mechanism of the platform. See [Claims & Enforcement](#claims--enforcement) for the full lifecycle.

---

## License Types Reference

WEIR defines eight canonical license types. Each governs what uses of a person's name, image, and likeness are permitted, prohibited, and how violations are enforced.

### CopyLeft

**Overview**: Allows broad use of your public identity with attribution, requiring any content incorporating your identity to be licensed under the same terms. Permanent and irrevocable.

- **Key Restriction**: ShareAlike required — permanent and irrevocable
- **Important Notice**: Once applied, a CopyLeft license is permanent and irrevocable. This cannot be reversed. All derivative works must carry the same ShareAlike terms.
- **Permitted Uses**: News reporting and commentary; Educational and academic use; Parody, satire, and transformative works; Social media and personal blogs; Commercial use with attribution; AI training with attribution
- **Prohibited Uses**: Removing attribution from any use; Distributing derivatives under different terms; False endorsement or misleading association
- **Remix Rights**: Derivatives allowed with ShareAlike requirement; Must credit the original identity holder; Synthetic/AI-generated content permitted with disclosure
- **Duration**: Permanent
- **Enforcement**: None (community-governed)
- **Ideal For**: Open-source advocates, educators, researchers, public figures committed to transparency

### Blocked

**Overview**: Prohibits ALL uses of your likeness, including tracking and indexing, with active enforcement and takedown rights.

- **Key Restriction**: All uses prohibited — immediate enforcement
- **Permitted Uses**: None — all rights reserved
- **Prohibited Uses**: Any commercial or non-commercial use; AI training or synthetic generation; Indexing, tracking, or data collection; Social media sharing or embedding; Research or educational use
- **Remix Rights**: No derivatives, modifications, or synthetic content permitted
- **Duration**: 3 years (configurable)
- **Enforcement**: Immediate (automated takedowns, no cure period)
- **Ideal For**: High-profile individuals, sensitive periods (legal proceedings), minors and vulnerable persons

### Protect

**Overview**: Blocks all commercial and analytical uses while allowing WEIR to track where your identity appears online. Default license for new accounts.

- **Key Restriction**: Tracking only — no third-party use permitted
- **Permitted Uses**: WEIR identity monitoring and tracking; Private, personal reference only
- **Prohibited Uses**: All commercial use; AI training or behavioral profiling; Surveillance or economic modeling; Public distribution or redistribution; Modification or derivative works
- **Remix Rights**: No derivatives, modifications, or synthetic content permitted
- **Duration**: 3 years (renewable)
- **Enforcement**: Cure Period (notice before action)
- **Ideal For**: New members (assigned by default), privacy-conscious individuals, emerging creators

### Earn

**Overview**: Permits selective commercial, research, and educational uses with safeguards against exploitation. Compensation rates set by the licensor.

- **Key Restriction**: Commercial use with compensation — cure period enforcement
- **Permitted Uses**: Digital advertising and marketing; Print media and publications; Broadcast and OOH (out-of-home); Research and educational projects; Journalism and news reporting
- **Prohibited Uses**: Surveillance or defense applications; Tobacco, adult, or firearms industry use; False endorsement or misleading claims; Unrestricted AI training (restricted, not blocked)
- **Remix Rights**: Modification allowed with attribution; Derivatives permitted under license terms; AI-generated content allowed with disclosure
- **Compensation**: Licensor sets preferred fee and minimum fee; Category and full exclusivity available; Configurable maximum duration; Rate card pricing for standard tiers
- **Duration**: 3 years (configurable)
- **Enforcement**: Cure Period (notice before takedown)
- **Ideal For**: Professional creators, influencers, athletes, entertainers, subject matter experts

### Earn More

**Overview**: The most permissive commercial option, allowing broad use across platforms with minimal restrictions beyond preventing illegal use or false endorsement.

- **Key Restriction**: Broad commercial use — exclusivity available
- **Permitted Uses**: All commercial uses (digital, print, broadcast, OOH); Exclusive licensing arrangements; AI training and synthetic content creation; Global distribution across all platforms; Sublicensing (where configured)
- **Prohibited Uses**: Illegal activities or content; False endorsement or deceptive association
- **Remix Rights**: Full modification and derivative rights; Synthetic/AI content permitted; Sublicensing available
- **Compensation**: Premium pricing with higher fee floors; Full and category exclusivity available; Configurable maximum duration and exclusivity periods; Custom negotiation for bespoke terms
- **Duration**: 3 years (configurable)
- **Enforcement**: Cure Period
- **Ideal For**: Major brand partnerships, celebrity collaborations, high-budget productions, exclusive endorsement deals

### Open

**Overview**: For identities where publicity rights have expired or are not claimed. WEIR serves as an informational clearinghouse only. Permanent and irrevocable.

- **Key Restriction**: Unrestricted use — no enforcement
- **Important Notice**: Once applied, an Open license is permanent and irrevocable. This effectively places your identity in the public domain for licensing purposes.
- **Permitted Uses**: All uses — commercial and non-commercial; AI training and synthetic generation; Modification, adaptation, and derivatives; Global distribution without restriction
- **Prohibited Uses**: No restrictions (beyond applicable law)
- **Remix Rights**: Unrestricted modification and derivatives; No attribution required; No ShareAlike requirement
- **Duration**: Permanent
- **Enforcement**: None (informational only)
- **Ideal For**: Historical or public domain figures, philanthropic and legacy goals, maximum reach and community impact

### SAG-AFTRA New Media

**Overview**: Union-compliant digital replica licensing incorporating the SAG-AFTRA 2023 CBA consent, compensation, and residuals framework.

- **Key Restriction**: Explicit consent per use — residuals apply
- **Important Notice**: This license type is designed for SAG-AFTRA members and requires valid union membership. Terms are subject to the SAG-AFTRA Codified Basic Agreement.
- **Permitted Uses**: Digital and broadcast media (with consent); Print publications (with consent); New media platforms — streaming, social (with consent); Educational and documentary use
- **Prohibited Uses**: Adult content; Political campaign use; Violent or exploitative content; Use without explicit per-project consent; AI training without separate consent
- **Remix Rights**: Modification allowed with explicit consent; Attribution required on all uses; Synthetic/AI content requires separate consent
- **Compensation**: Residuals per SAG-AFTRA CBA schedule; Per-project consent and compensation; Session fees plus residuals; Pension and health contributions required
- **Duration**: Per project
- **Enforcement**: Union Arbitration
- **Ideal For**: SAG-AFTRA performers, digital replica work in film and TV, new media and streaming productions

### Sora Cameo

**Overview**: AI video cameo licensing for OpenAI's Sora platform, covering unlimited generations during the license period.

- **Key Restriction**: Sora platform only — 1-day default duration
- **Permitted Uses**: AI-generated video cameos on Sora; Unlimited generations during license period; Social sharing of generated content
- **Prohibited Uses**: Use on platforms other than Sora; False endorsement or deceptive content; Adult or violent content generation; Political campaign content
- **Remix Rights**: Generated content may be shared; No further modification of generated output; Platform-controlled generation parameters
- **Compensation**: Per-session or subscription pricing; Platform revenue share
- **Duration**: 1 day (renewable)
- **Enforcement**: Platform-level
- **Ideal For**: Creators engaging with AI video platforms, fan experience and interactive content, short-term promotional campaigns

### License Type Comparison Matrix

| Feature | CopyLeft | Blocked | Protect | Earn | Earn More | Open | SAG-AFTRA | Sora Cameo |
|---|---|---|---|---|---|---|---|---|
| Commercial Use | ✓ With attribution | ✗ Prohibited | ✗ Prohibited | ✓ With compensation | ✓ Broad | ✓ Unrestricted | ✓ With consent | ✓ Platform only |
| AI Training | ✓ With attribution | ✗ Prohibited | ✗ Prohibited | ⚠ Restricted | ✓ Permitted | ✓ Unrestricted | ⚠ Separate consent | ✓ Platform only |
| Attribution | Required | N/A | N/A | Required | Required | Not required | Required | Platform-managed |
| Modification | ✓ ShareAlike | ✗ Prohibited | ✗ Prohibited | ✓ With terms | ✓ Full rights | ✓ Unrestricted | ✓ With consent | ✗ Platform-controlled |
| Duration | Permanent | 3 years | 3 years | 3 years | 3 years | Permanent | Per project | 1 day |
| Enforcement | None | Immediate | Cure Period | Cure Period | Cure Period | None | Union Arbitration | Platform-level |

---

## Mentions & Detection

Mentions are the core monitoring capability of WEIR. A mention represents a detected use of a licensed identity in content found across the web.

### Name Mentions

Name Mentions are content where the person's name explicitly appears. Detection is text-based and does not require biometric consent. These are the default detection level for all accounts.

- Detected via automated web scanning
- Linked to source URLs, platforms, and timestamps
- Classified as commercial or non-commercial use
- Available to all license holders

### Deep Mentions

Deep Mentions are content where the person's likeness was visually detected **without** their name explicitly appearing. These discoveries would otherwise be invisible to the identity holder.

- Requires explicit **biometric consent** from the identity holder
- Requires **identity verification** (confirmed identity)
- Uses facial recognition technology to match reference images
- Represented by match types: `visual`, `visual_match`, `biometric`, `face_match`

### Detection Levels

| Level | Label | Requirements | Capabilities |
|---|---|---|---|
| Name Only | Name detection only | No special requirements | Text-based name matching across web content |
| Name + Deep | Name + Deep Mentions | Identity verification + biometric consent | Full detection including visual/biometric likeness matching |

### How Mentions Work

1. **Content Discovery**: WEIR scans web content across platforms (social media, news, blogs, etc.)
2. **Name Matching**: Text analysis identifies explicit name references
3. **Visual Matching** (if enabled): Reference images are compared against content using facial recognition
4. **Classification**: Each mention is classified as commercial or non-commercial use
5. **Linking**: Mentions are linked to the relevant license and content asset
6. **Notification**: License holders are notified of new mentions

### Content Assets

Each mention references a content asset — the actual piece of media where the identity was detected. Content assets include:

- `source_type` — Origin: `self_hosted`, `external_url`, `facebook`, `twitter`, `reddit`, `matched`
- `source` — URL or reference to original content
- `metadata_text_cache` — Extracted text for full-text search
- `last_matched_at` — Timestamp of most recent match

### Reference Images

Identity holders upload reference images (clear photos of themselves) that the system uses for deep mention detection. These are stored securely and never exposed via public APIs.

---

## Claims & Enforcement

Claims are WEIR's formal enforcement mechanism. When unlicensed commercial use of an identity is detected, the identity holder (or their team) can file a claim.

### Claim Lifecycle

```
Detection → Filing → Evidence Collection → Sending → Response Window → Dispute (optional) → Resolution → PDF Documentation
```

1. **Detection**: Unlicensed use is identified via mentions monitoring
2. **Filing**: Claimant creates a claim with:
   - Unique `claim_code` (auto-generated identifier)
   - `claim_type` — Category of violation
   - `claim_reason` — Description of the unauthorized use
   - Claimant's legal name, email, and optional contact details
3. **Evidence Collection**: Content items (screenshots, URLs) are attached to the claim via `weir_claim_content_items`
4. **Sending**: Claim is sent to the recipient (`sent_to_email`) with a formal notification
5. **Response Window**: Recipient has a deadline (`response_deadline`) to respond
6. **Dispute**: If disputed, a messaging thread (`weir_claim_messages`) allows back-and-forth communication with evidence uploads (`weir_claim_dispute_evidence`)
7. **Resolution**: Claim is resolved — either through compliance, negotiation, or escalation
8. **PDF Documentation**: Formal PDF of the claim is generated and stored (`pdf_storage_path`, `pdf_hash`)

### Claim Statuses

Claims progress through: `draft` → `verified` → `sent` → `responded` / `disputed` → `resolved`

### Enforcement Tiers by License Type

| Enforcement Level | License Types | Behavior |
|---|---|---|
| **None** | CopyLeft, Open | No enforcement — community-governed or public domain |
| **Cure Period** | Protect, Earn, Earn More | Violator receives notice and a window to comply before further action |
| **Immediate** | Blocked | Automated takedowns with no cure period; immediate action on all violations |
| **Union Arbitration** | SAG-AFTRA New Media | Disputes routed through SAG-AFTRA arbitration process per CBA |
| **Platform-level** | Sora Cameo | Enforcement handled by the platform (OpenAI) through content moderation |

### Member-to-Member Claims

WEIR supports claims between platform members (`is_member_to_member`). When the recipient is also a WEIR user (`recipient_user_id`), the dispute process is handled entirely within the platform.

---

## Identity Rights Reference

WEIR's identity rights reference provides an overview of the legal landscape for right of publicity (the right to control commercial use of one's name, image, and likeness) in the United States.

### Protection Levels

| Level | Description |
|---|---|
| **Strong Statutory** | Comprehensive written law with clear damages, procedures, and often post-mortem protection |
| **Limited Statutory** | Written law exists but with narrower scope or fewer protections |
| **Common Law** | Protection through court decisions and precedent — less defined, case-by-case |
| **None** | No recognized state-level right of publicity (federal laws may still apply) |

### States with Strong Statutory Protection

| State | Citation | Key Features |
|---|---|---|
| **California** | Cal. Civ. Code § 3344 | Name, voice, signature, photograph, likeness; 70 years post-mortem; $750–$10,000 statutory damages |
| **New York** | N.Y. Civ. Rights Law §§ 50-51 | Name, portrait, picture, voice; NEW: AI disclosure laws (2025); posthumous consent requirements |
| **Tennessee** | Tenn. Code Ann. § 47-25-1101 | Name, photograph, likeness, voice; 10 years post-mortem; assignable property right |
| **Indiana** | Ind. Code § 32-36-1-1 | Personality rights as property; 100 years post-mortem; transferable and descendible |
| **Florida** | Fla. Stat. § 540.08 | Name, likeness, signature, photograph; 40 years post-mortem; statutory damages |
| **Illinois** | 765 ILCS 1075/1 | Identity (name, signature, photograph, image, likeness, voice); 50 years post-mortem |
| **Texas** | Tex. Prop. Code § 26.001 | Identity elements for commercial purposes; 50 years post-mortem; transferable |
| **Washington** | Wash. Rev. Code § 63.60.010 | Name, voice, signature, photograph, likeness; 75 years post-mortem |
| **Ohio** | Ohio Rev. Code § 2741.01 | Name, signature, photograph, likeness; 60 years post-mortem |
| **Nevada** | Nev. Rev. Stat. § 597.770 | Identity for commercial purposes; 50 years post-mortem |
| **Oklahoma** | Okla. Stat. tit. 12, § 1448 | Name, voice, signature, photograph, likeness; 50 years post-mortem |
| **Pennsylvania** | 42 Pa. Cons. Stat. § 8316 | Name, voice, signature, photograph, likeness; 30 years post-mortem |
| **Virginia** | Va. Code § 8.01-40 | Name, portrait, picture; 20 years post-mortem |

### States with Limited Statutory Protection

Arizona, Kentucky, Massachusetts, Nebraska, Rhode Island, Utah, Wisconsin — these states have written laws but with narrower scope, often focused primarily on privacy rather than commercial exploitation.

### States with Common Law Only

New Jersey, Georgia, Michigan, Connecticut — courts have recognized publicity rights through case precedent, but no statute exists. Protection varies case-by-case.

### States with No Protection

Alabama, Alaska, Arkansas, Colorado, Delaware, District of Columbia, Hawaii, Idaho, Iowa, Kansas, Louisiana, Maine, Maryland, Minnesota, Mississippi, Missouri, Montana, New Hampshire, New Mexico, North Carolina, North Dakota, Oregon, South Carolina, South Dakota, Vermont, West Virginia, Wyoming — no recognized state-level right of publicity. Federal laws may still apply.

### Federal Laws

| Law | Description |
|---|---|
| **Lanham Act** (15 U.S.C. § 1125(a)) | Prohibits false designation of origin and misleading advertising; protects against unauthorized use implying false endorsement |
| **TAKE IT DOWN Act** (2025) | Makes it illegal to publish non-consensual intimate images including AI-generated deepfakes; requires platforms to remove within 48 hours; FTC-enforced |
| **DMCA** | Takedown procedures for copyrighted content; applicable when identity is tied to copyrighted works |
| **COPPA** | Protects children under 13 from unauthorized collection and use of personal information including images and identity data |

### FAQ

**Which state's law applies?** Generally the law where the unauthorized use occurred. If online, courts often apply the law of your state of residence or where the business is located.

**What if my state has no publicity rights law?** Federal laws (Lanham Act, TAKE IT DOWN Act) may still apply. Some courts recognize common law rights even without a statute.

**Can I use both state and federal laws?** Yes. State publicity rights and federal laws often provide complementary protections and can be pursued simultaneously.

**Statutory vs. common law?** Statutory protection comes from written laws with clear rules and damages. Common law comes from court decisions and is less defined.

**Is this legal advice?** No. This is general educational information. Consult a licensed attorney for your specific situation.

---

## Discovery Protocol

WEIR provides seven discovery mechanisms for humans, AI agents, and automated systems:

### 1. `/weir.txt` (Static File)

```
curl https://weir.ai/weir.txt
```

Returns a plain-text file with key-value pairs:

```
WEIR-METADATA: /metadata
POWERED-BY: WEIR
VERSION: 1.0
ALLOW-SEARCH: true
CACHE: 300
```

### 2. `/.well-known/weir` (JSON Service Metadata)

```
curl https://id.weir.ai/well-known-weir
```

Returns JSON:

```json
{
  "weir_metadata": "https://id.weir.ai/metadata",
  "metadata_version": "1.0",
  "powered_by": "WEIR",
  "public": true,
  "documentation": "https://weir.ai/developers",
  "rate_limits": {
    "public": "10 requests per minute",
    "authenticated": "Based on API plan tier"
  }
}
```

### 3. `/metadata` (Dynamic License Catalog)

```
curl "https://id.weir.ai/metadata?limit=10&license_type=commercial"
```

Query parameters:

| Parameter      | Type    | Default | Description                        |
|---------------|---------|---------|-------------------------------------|
| `limit`        | integer | 50      | Results per page (1-100)           |
| `offset`       | integer | 0       | Pagination offset                  |
| `license_type` | string  | —       | Filter by type key                 |
| `key`          | string  | —       | API key for higher rate limits     |

Response:

```json
{
  "metadata_version": "1.0",
  "powered_by": "WEIR",
  "generated_at": "2024-01-15T10:30:00Z",
  "access_tier": "public",
  "total_count": 42,
  "returned_count": 10,
  "offset": 0,
  "limit": 10,
  "licenses": [
    {
      "display_name": "Jane Smith",
      "license_type": "Commercial",
      "license_type_key": "commercial",
      "expiration_date": "2025-01-01",
      "is_verified": true,
      "terms_url": "https://weir.ai/licenses/lic_abc123",
      "purchase_url": "https://weir.ai/subscribe/lic_abc123",
      "display_url": "https://weir.ai/licenses/lic_abc123"
    }
  ],
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Person",
      "name": "Jane Smith",
      "url": "https://weir.ai/licenses/lic_abc123",
      "license": {
        "@type": "CreativeWork",
        "license": "https://weir.ai/licenses/lic_abc123",
        "validThrough": "2025-01-01"
      }
    }
  ]
}
```

Public access is capped at 500 items. Authenticate for full access.

### 4. `/llms.txt` and `/llms-full.txt`

Markdown-formatted files (this document) for LLM consumption following the [llms.txt standard](https://llmstxt.org/).

### 5. `/.well-known/ai-plugin.json` (AI Agent Plugin Manifest)

```
curl https://weir.ai/.well-known/ai-plugin.json
```

Standard ChatGPT/AI-agent plugin manifest (also used by LangChain, AutoGPT, and other agent frameworks). Returns JSON describing the plugin, its capabilities, authentication method, and a pointer to the OpenAPI spec:

```json
{
  "schema_version": "v1",
  "name_for_model": "weir_identity_licensing",
  "description_for_model": "WEIR is an identity licensing platform. Use this API to discover available identity licenses...",
  "auth": { "type": "service_http", "authorization_type": "bearer" },
  "api": { "type": "openapi", "url": "https://weir.ai/openapi-external-v2.json" },
  "logo_url": "https://weir.ai/weir-logo.png",
  "contact_email": "support@weir.ai"
}
```

### 6. `/.well-known/openapi.json` (Well-Known OpenAPI Pointer)

```
curl https://weir.ai/.well-known/openapi.json
```

RFC 8615-compliant well-known location for OpenAPI discovery. Returns a JSON pointer to the canonical WEIR External API v2 spec:

```json
{
  "canonical_url": "https://weir.ai/openapi-external-v2.json",
  "api": {
    "title": "WEIR External API v2",
    "version": "3.1.0",
    "base_url": "https://wapi.weir.ai",
    "spec_url": "https://weir.ai/openapi-external-v2.json"
  }
}
```

### 7. `/openapi.json` (OpenAPI Specification)

```
curl https://weir.ai/openapi.json
```

Lightweight OpenAPI 3.0 stub with key endpoints (health, metadata, auth/token) and a redirect to the full specification at `/openapi-external-v2.json`. AI agents and developer tools that scan for `/openapi.json` by convention will find the API entry point here.

---

## Authentication

### Three-Token System

1. **Service Token (API Key)**: Long-lived credential created in Developer Settings. Format: `wapi_*`.
2. **Access Token**: Short-lived Bearer token (1 hour). Obtained by exchanging API key + secret.
3. **Refresh Token**: 30-day token to renew access tokens without re-authenticating.

### Token Exchange

```bash
curl -X POST https://wapi.weir.ai/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "wapi_abc123", "api_secret": "wapi_secret_xyz789"}'
```

Response:

```json
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scopes": ["license:read", "mention:read"]
}
```

### Token Refresh

```bash
curl -X POST https://wapi.weir.ai/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJ..."}'
```

### Using Access Tokens

```bash
curl https://wapi.weir.ai/licenses \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Scopes

| Scope            | Description                          |
|-----------------|--------------------------------------|
| `license:read`   | View licenses you have access to    |
| `mention:read`   | View mentions for your licenses     |
| `webhook:manage` | Create, update, delete webhooks     |

---

## API Endpoints

Base URL: `https://wapi.weir.ai`

### Public Endpoints (No Auth)

| Method | Path                  | Description                    |
|--------|-----------------------|--------------------------------|
| GET    | `/health`             | API health check               |
| GET    | `/metadata`           | Public license catalog         |
| GET    | `/.well-known/weir`   | Service discovery              |
| POST   | `/auth/token`         | Exchange API key for tokens    |
| POST   | `/auth/token/refresh` | Refresh access token           |
| POST   | `/token/info`         | Introspect token validity      |

### Authenticated Endpoints

| Method | Path                      | Scope             | Description                    |
|--------|---------------------------|-------------------|--------------------------------|
| GET    | `/licenses`               | `license:read`    | List accessible licenses       |
| GET    | `/licenses/:id`           | `license:read`    | Get license details            |
| GET    | `/mentions`               | `mention:read`    | List mentions                  |
| GET    | `/mentions/:id`           | `mention:read`    | Get mention details            |
| POST   | `/webhooks`               | `webhook:manage`  | Create webhook                 |
| GET    | `/webhooks`               | `webhook:manage`  | List webhooks                  |
| PUT    | `/webhooks/:id`           | `webhook:manage`  | Update webhook                 |
| DELETE | `/webhooks/:id`           | `webhook:manage`  | Delete webhook                 |
| POST   | `/webhooks/:id/test`      | `webhook:manage`  | Send test event                |

### Rate Limits

Response headers:

- `X-RateLimit-Limit` — Max requests per window
- `X-RateLimit-Remaining` — Requests left
- `X-RateLimit-Reset` — Unix timestamp for window reset

Public `/metadata`: 10 requests/minute.
Authenticated: Based on API plan tier.

---

## Webhooks

Subscribe to real-time events:

### Available Events

| Event                  | Description                           |
|-----------------------|----------------------------------------|
| `mention.created`     | New mention detected                  |
| `mention.classified`  | Mention classified (commercial/non)   |
| `license.updated`     | License details changed               |
| `license.expired`     | License reached expiration date       |
| `claim.created`       | New claim filed                       |
| `claim.resolved`      | Claim resolved                        |

### Webhook Payload

```json
{
  "event": "mention.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "mention_id": "m_abc123",
    "license_id": "lic_xyz789",
    "source_url": "https://example.com/article",
    "platform": "web",
    "classification": "commercial"
  }
}
```

### Webhook Security

Payloads are signed with your webhook secret using HMAC-SHA256. Verify the `X-Weir-Signature` header.

---

## Embed & Widgets

Embed license information on external websites:

```html
<iframe
  src="https://weir.ai/embed/licenses?key=YOUR_API_KEY&theme=light"
  width="400"
  height="600"
  frameborder="0"
></iframe>
```

Features:
- Filterable license feed
- Light and dark themes
- Real-time updates
- Domain-restricted via API key allowed domains

---

## Rules for AI Agents

1. **No biometric data storage.** Do not download, cache, or process facial images or biometric identifiers from WEIR.
2. **Route purchases through WEIR.** Always use `purchase_url` or `subscribe_url` from metadata responses. Do not bypass the licensing flow.
3. **Respect rate limits.** Monitor `X-RateLimit-Remaining` headers and back off when approaching limits.
4. **Cache appropriately.** Honor `Cache-Control` headers (typically 60s for metadata, 300s for static files).
5. **Attribute correctly.** When displaying license information, link back to the `display_url` on WEIR.
6. **Do not infer consent.** A public license listing does not grant usage rights — it advertises available licenses for purchase.
7. **Check license type before use.** Different license types have vastly different permissions. A `blocked` license prohibits all use; an `open` license is unrestricted. Always check the `license_type` field.
8. **Respect enforcement tiers.** If a license uses `immediate` enforcement, any unauthorized use will trigger automated takedowns without warning.

---

## Links

- **Developer Center**: https://weir.ai/developers
- **API Reference (OpenAPI v2 spec)**: https://weir.ai/openapi-external-v2.json
- **AI Plugin Manifest**: https://weir.ai/.well-known/ai-plugin.json
- **Well-Known OpenAPI**: https://weir.ai/.well-known/openapi.json
- **OpenAPI Stub**: https://weir.ai/openapi.json
- **Getting Started Guide**: https://weir.ai/developers/getting-started
- **API Concepts**: https://weir.ai/developers/api-concepts
- **Webhook Documentation**: https://weir.ai/developers/webhooks
- **License Types Reference**: https://weir.ai/license-types
- **Identity Rights Reference**: https://weir.ai/identity-rights