# Signa API Documentation

> Global trademark intelligence platform. Search, retrieve, and monitor trademarks from one API — 10 production offices (USPTO, EUIPO, INPI France, IP Australia, CIPO, WIPO, IPOS, PRV Sweden, IPI Switzerland, NIPO Norway) covering ~29M trademarks, with more rolling out. Monitoring (watches, alerts, webhooks) is live in beta.

## Getting Started
- [Introduction](index.mdx): Platform overview, office coverage, quick example
- [Quickstart](quickstart.mdx): First API call in 5 minutes, SDK setup
- [Changelog](changelog.mdx): API behavior changes, deprecations, fixes

## Core Concepts
- [Trademarks](guides/trademarks.mdx): Lifecycle, status taxonomy, key fields
- [Search](guides/search.mdx): Text, phonetic, fuzzy search, filters, aggregations
- [Entities](guides/entities.mdx): Owners, attorneys, firms, entity resolution
- [Classifications](guides/classifications.mdx): Nice classes, goods/services, design codes
- [Deadline Rules](guides/deadline-rules.mdx): 21-jurisdiction ruleset, computation, US Section 8/9
- [Madrid Protocol](guides/madrid-protocol.mdx): International registrations, designations

## Monitoring (beta)
- [Monitoring overview](guides/monitoring/overview.mdx): Watches detect trademark events; alerts and webhooks deliver them
- [Known beta limitations](guides/monitoring/beta-limitations.mdx): Delivery modes, replay, alert latency by office sync cadence, preview budget, diagnostics windows
- [Watches](guides/monitoring/watches.mdx): Five watch types, the canonical camelCase query DSL, preview, bulk create, replay
- [Recipe: US-only class watch](guides/monitoring/us-watch-recipe.mdx): Preview → create → webhook → polling fallback, end to end
- [Opposition windows](guides/monitoring/opposition-windows.mdx): Jurisdiction-aware deadlines on alerts
- [Webhooks](guides/monitoring/webhooks.mdx): Endpoint setup, alert.created payload (trademark_id), retries, rotation, auto-disable, test deliveries
- [Verify webhook signatures](guides/monitoring/webhook-signature-verification.mdx): Standard Webhooks HMAC verification recipes
- [Handling alerts](guides/monitoring/alert-handling.mdx): Pull vs push, dedup by webhook-id, reconciliation via POST /v1/alerts/lookup, replay handling
- [Pipe alerts into Slack](guides/monitoring/slack-via-webhook.mdx): Cloudflare Worker / AWS Lambda recipes
- [Troubleshooting](guides/monitoring/troubleshooting.mdx): Diagnostics endpoint — why didn't my alert fire
- [Uptime monitoring](guides/monitoring/uptime-monitoring.mdx): Health endpoints, what readiness does and doesn't cover

## How Signa Works
- [Status Taxonomy](guides/status-taxonomy.mdx): 4-axis system, 18 stages, office mappings
- [Data Freshness](guides/data-freshness.mdx): Per-office sync schedules, consistency model
- [Filing Routes](guides/filing-routes.mdx): National vs Madrid vs regional, mark types
- [Entity Resolution](guides/entity-resolution.mdx): Name normalization, SEC/GLEIF matching

## Working with the API
- [Caching](guides/caching.mdx): ETags, conditional requests, strategies
- [Resilience](guides/resilience.mdx): Backoff, retry, circuit breaker, Idempotency-Key semantics (required on mutations; exempt read-shaped POSTs)
- [Testing](guides/testing.mdx): Sandbox, fixtures, integration test patterns

## Trust & Compliance
- [Data Quality](guides/data-quality.mdx): Office coverage matrix, audit results, freshness SLAs
- [Compliance](guides/compliance.mdx): GDPR, attorney privilege, security, data residency
- [Glossary](guides/glossary.mdx): 25+ trademark terms with API field mappings

## Use Cases
- [Trademark Clearance](guides/use-cases/trademark-clearance.mdx): Brand screening workflow
- [Competitor Intelligence](guides/use-cases/competitor-intelligence.mdx): Track competitor filings
- [Renewal Management](guides/use-cases/renewal-management.mdx): Deadline tracking across jurisdictions
- [M&A Due Diligence](guides/use-cases/mna-due-diligence.mdx): Portfolio evaluation
- [Opposition Tracking](guides/use-cases/opposition-tracking.mdx): TTAB proceedings
- [Class Coverage Audits](guides/use-cases/class-coverage-audits.mdx): Nice class gap analysis
- [Ownership Transfer](guides/use-cases/ownership-transfer.mdx): Post-acquisition workflows

## API Reference
- [Introduction](api-reference/introduction.mdx): Base URL, authentication, the 7-scope registry, request/response format, status codes
- [Pagination](api-reference/pagination.mdx): Cursor-based pagination, has_more, pagination.total_count via include_total (with total_count_approximate and the 10k cap), fixed-size bulk envelopes
- [Rate Limits & Quotas](api-reference/rate-limits.mdx): Monthly quota pools, per-endpoint-type per-minute limits (beta: search 1,000/min, read 10,000/min, monitoring 100/min, utility/reference/check 1,000/min), dual-constraint RateLimit headers, X-Quota daily/monthly unit headers, 429 handling
- [Errors](api-reference/errors.mdx): Error catalog, idempotency exemptions and replay semantics, troubleshooting
- [Health](api-reference/health.mdx): Unauthenticated liveness/readiness probes
- Trademarks: search (GET/POST /v1/trademarks), get, batch, history, changes, related, suggest, image search, coverage, media, proceedings, source
- Monitoring — Watches: create, list, retrieve, update, delete, pause, resume, replay, bulk, preview (estimate_basis, 429 concurrency, preview_timeout), diagnostics
- Monitoring — Alerts: list, retrieve, lookup (bulk by ID), list-for-watch
- Monitoring — Webhooks: create, list, retrieve, update, delete, rotate-secret, test, deliveries, redeliver
- Parties: owners, entities, attorneys, firms (get, list, trademarks, related)
- Proceedings: list, get
- Reference Data: offices, jurisdictions, classifications, design codes, event types, deadline rules, opposition rules, goods-services
- Administration: me (plan enum includes beta), usage (by_endpoint_type + rate_limits), usage summary, API keys (create/rotate/update/revoke — idempotency-enforced), logs

## SDK
- [TypeScript SDK](sdk/overview.mdx): Installation, configuration, usage patterns
- [Error Handling](sdk/error-handling.mdx): Typed error classes, automatic retries, Retry-After handling
- [Pagination](sdk/pagination.mdx): Auto-pagination helpers

## MCP
- [MCP Overview](mcp/overview.mdx): Signa tools for AI agents
- [Tools Reference](mcp/tools.mdx): search_trademarks and friends — office codes case-insensitive