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 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.

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

AI Agent Integration Example

How an AI agent might discover and use WEIR license metadata

// 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.