# Metadata Discovery Enable AI agents and crawlers to discover available licenses ### WEIR Discovery Protocol Seven standardized endpoints for automated license discovery WEIR provides machine-readable metadata endpoints that enable AI agents, crawlers, and external services to discover available identity licenses. This follows established patterns like `robots.txt`, `.well-known`, and `llms.txt` for web service discovery. #### /weir.txt Static discovery file ``` curl https://weir.ai/weir.txt ``` Response: ``` # WEIR Identity Rights Discovery # https://weir.ai WEIR-METADATA: /metadata POWERED-BY: WEIR VERSION: 1.0 # Public license metadata is available at the URL above. # This does not grant rights to store biometric or personal data. # External agents must route all purchases to WEIR. # Caching allowed up to 300 seconds. ALLOW-SEARCH: true CACHE: 300 ``` ### /.well-known/weir JSON JSON service metadata following RFC 8615 well-known URI pattern ``` curl https://id.weir.ai/well-known-weir ``` Response: ``` { "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" } } ``` ### /metadata Dynamic API Query available licenses with filtering, pagination, and JSON-LD structured data Basic Request With Filters Authenticated ``` curl https://id.weir.ai/metadata ``` Response Structure: ``` { "metadata": { "version": "1.0", "generated_at": "2024-01-15T10:30:00Z", "total_licenses": 42, "rate_limit": { "remaining": 9, "limit": 10, "reset_in_seconds": 60 } }, "licenses": [ { "external_id": "lic_abc123", "display_name": "Jane Smith", "license_type": "commercial", "status": "public", "valid_from": "2024-01-01", "valid_until": "2025-01-01", "subscribe_url": "https://weir.ai/subscribe/lic_abc123", "detail_url": "https://weir.ai/licenses/lic_abc123" } ], "jsonld": { "@context": "https://schema.org", "@graph": [...] } } ``` ### /llms.txt Markdown LLM-friendly documentation following the [llms.txt standard](https://llmstxt.org/) for AI model discovery The `/llms.txt` file provides a concise Markdown summary of WEIR for large language models. A more detailed version is available at `/llms-full.txt` with complete API documentation, authentication flows, and code examples. ``` # Fetch concise LLM documentation curl https://weir.ai/llms.txt # Fetch full LLM documentation curl https://weir.ai/llms-full.txt ``` What's included: - **llms.txt** — Core concepts, discovery endpoints, API overview, agent rules - **llms-full.txt** — Complete API reference, auth flows, webhook events, embed docs ### /.well-known/ai-plugin.json JSON AI agent plugin manifest for ChatGPT, LangChain, AutoGPT, and other agent frameworks Standard plugin manifest originally defined for ChatGPT plugins but widely adopted by AI agent frameworks. Describes the service, its capabilities, authentication method, and points to the OpenAPI specification. ``` curl https://weir.ai/.well-known/ai-plugin.json ``` Response: ``` { "schema_version": "v1", "name_for_human": "WEIR Identity Rights", "name_for_model": "weir_identity_rights", "description_for_model": "WEIR is an identity rights platform...", "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" } ``` ### /.well-known/openapi.json JSON RFC 8615-compliant well-known location pointing to the canonical OpenAPI specification Some AI agents and developer tools scan the `/.well-known/` directory for an `openapi.json` file following the RFC 8615 pattern. This file acts as a pointer to the full WEIR External API v2 specification. ``` curl https://weir.ai/.well-known/openapi.json ``` Response: ``` { "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" } } ``` ### /openapi.json OpenAPI 3.0 Lightweight OpenAPI stub with key endpoints, redirecting to the full v2 specification Many developer tools and AI agents scan for `/openapi.json` by convention. This file provides a lightweight OpenAPI 3.0 stub with the most common endpoints (health, metadata, auth) and an `externalDocs` reference to the complete specification at `/openapi-external-v2.json`. ``` curl https://weir.ai/openapi.json ``` Key endpoints included: - `GET /health` — Health check (public) - `GET /metadata` — Public license catalog (public) - `POST /auth/token` — Exchange API key for access token For the complete specification with all endpoints, see [/openapi-external-v2.json](/content/openapi-external-v2.json). ### JSON-LD Structured Data Schema.org-compatible structured data for semantic understanding The `/metadata` endpoint includes a JSON-LD graph that AI agents can use for semantic understanding of license data. Each license is represented as a `DigitalDocument` with linked `Person` entities. ``` { "@context": "https://schema.org", "@graph": [ { "@type": "DigitalDocument", "@id": "https://weir.ai/licenses/lic_abc123", "name": "Jane Smith - Commercial License", "description": "Commercial usage rights for identity", "dateCreated": "2024-01-01", "expires": "2025-01-01", "license": "https://weir.ai/license-types/commercial", "author": { "@type": "Person", "name": "Jane Smith" } } ] } ``` ### Rate Limits | Access Type | Rate Limit | Notes | | --- | --- | --- | | Public (no auth) | 10 requests/minute | Suitable for discovery and testing | | Authenticated | Based on API plan | Higher limits for production use | ### AI Agent Integration Example How an AI agent might discover and use WEIR license metadata ```javascript // 1. Discover WEIR metadata endpoint const wellKnown = await fetch('/.well-known/weir').then(r => r.json()); const metadataUrl = wellKnown.weir_metadata; // 2. Query available licenses const { licenses, jsonld } = await fetch(metadataUrl).then(r => r.json()); // 3. Find licenses for a specific person const janeLicenses = licenses.filter(l => l.display_name.toLowerCase().includes('jane') ); // 4. Direct users to subscribe if (janeLicenses.length > 0) { const subscribeUrl = janeLicenses[0].subscribe_url; // Route user to WEIR for licensing } ``` **Important:** External agents must route all purchases through WEIR. Direct data scraping or biometric storage is prohibited.