> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Trademark Coverage

> Madrid Protocol designation territories and their per-territory protection status

## Overview

Lists the territories designated under a Madrid Protocol International Registration and the per-territory protection status. This endpoint is meaningful only for marks with `filing_route = madrid_designation`. For non-Madrid marks the response is an empty list.

Use this to see which jurisdictions an IR currently covers, what each one's status is, and when each designation was made or refused.

## Path Parameters

<ParamField path="id" type="string" required>
  Trademark ID (`tm_...`).
</ParamField>

## Query Parameters

<ParamField query="protection_status" type="string">
  Filter by per-territory protection status. One of `designated`, `provisionally_refused`, `finally_refused`, `protected`, `withdrawn`, `renounced`, `ceased`, `invalidated`, `limited`, `expired`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Page size (1-100).
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response.
</ParamField>

## Response

<ResponseField name="data" type="object[]">
  Array of coverage records.
</ResponseField>

<ResponseField name="data[].territory_code" type="string">
  Two-letter ISO territory code (e.g. `US`, `DE`, `JP`).
</ResponseField>

<ResponseField name="data[].territory_name" type="string">
  Human-readable territory name.
</ResponseField>

<ResponseField name="data[].protection_status" type="string">
  Current protection status in the territory.
</ResponseField>

<ResponseField name="data[].designation_date" type="string">
  ISO date the territory was first designated.
</ResponseField>

<ResponseField name="data[].protection_date" type="string">
  ISO date protection took effect, when granted.
</ResponseField>

<ResponseField name="data[].refusal_date" type="string">
  ISO date of refusal, when applicable.
</ResponseField>

<ResponseField name="data[].status_effective_date" type="string">
  ISO date the current protection status became effective.
</ResponseField>

<ResponseField name="data[].is_subsequent_designation" type="boolean">
  `true` when this territory was added after the original IR filing.
</ResponseField>

<ResponseField name="data[].designation_protocol" type="string">
  Madrid Protocol article under which the designation was made.
</ResponseField>

<ResponseField name="data[].goods_limitations" type="string">
  Free-text limitation of the goods/services list for this territory, when applicable.
</ResponseField>

<ResponseField name="data[].status_detail" type="string">
  Additional status detail or office note.
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "territory_code": "US",
        "territory_name": "United States",
        "protection_status": "protected",
        "designation_date": "2024-03-15",
        "protection_date": "2025-01-21",
        "refusal_date": null,
        "status_effective_date": "2025-01-21",
        "is_subsequent_designation": false,
        "designation_protocol": "p",
        "goods_limitations": null,
        "status_detail": null
      },
      {
        "territory_code": "DE",
        "territory_name": "Germany",
        "protection_status": "provisionally_refused",
        "designation_date": "2024-03-15",
        "protection_date": null,
        "refusal_date": "2024-09-02",
        "status_effective_date": "2024-09-02",
        "is_subsequent_designation": false,
        "designation_protocol": "p",
        "goods_limitations": null,
        "status_detail": "Likelihood of confusion with prior right"
      }
    ],
    "has_more": false,
    "pagination": { "cursor": null },
    "request_id": "req_xyz"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/trademarks/tm_abc123/coverage?protection_status=protected" \
    -H "Authorization: Bearer sig_YOUR_KEY"
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

  const coverage = await signa.trademarks.coverage("tm_abc123", {
    protection_status: "protected",
  });

  for (const c of coverage.data) {
    console.log(c.territory_code, c.protection_status);
  }
  ```
</CodeGroup>

## Errors

| Status | Type               | Description                             |
| ------ | ------------------ | --------------------------------------- |
| 400    | `validation_error` | Invalid query parameter or trademark ID |
| 401    | `unauthorized`     | Missing or invalid API key              |
| 404    | `not_found`        | Trademark not found                     |
| 429    | `rate_limited`     | Too many requests                       |

## Related Endpoints

* [Get Trademark](/api-reference/trademarks/get-trademark): parent IR detail
* [Madrid Protocol guide](/guides/madrid-protocol): how Madrid filings, designations, and basic marks fit together
* [Trademark Related](/api-reference/trademarks/trademark-related): basic mark and other related records