> ## 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 Changes

> Version-level diff history showing what changed on a trademark and when

## Overview

Returns the diff log from the change-history ledger for a single mark, reverse chronological by default. Each entry captures the fields that changed in one update, the old and new values, and the source data date. Use this when you need an audit trail of how a record evolved (status flips, owner changes, classification edits) rather than the office event timeline you get from [`/history`](/api-reference/trademarks/trademark-history).

## Path Parameters

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

## Query Parameters

<ParamField query="changed_field" type="string">
  Restrict to versions whose `changed_fields` array includes this field name. Parent-field changes use snake\_case field names (e.g. `status_stage`, `mark_text_primary`, `expiry_date`). Child-entity changes use related entity types (classifications, owners, attorneys, events).
</ParamField>

<ParamField query="sort" type="string" default="-changed_at">
  Sort order. One of `-changed_at` (newest first, default) or `changed_at` (oldest first).
</ParamField>

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

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

## Response

<ResponseField name="data" type="object[]">
  Array of change records ordered by `created_at`.
</ResponseField>

<ResponseField name="data[].version" type="integer">
  Monotonically increasing version number for this trademark.
</ResponseField>

<ResponseField name="data[].change_type" type="string">
  Change classification (e.g. `created`, `updated`, `corrected`).
</ResponseField>

<ResponseField name="data[].changed_fields" type="string[]">
  Names of fields touched in this version.
</ResponseField>

<ResponseField name="data[].old_values" type="object">
  Field-keyed object of values before the change. `null` for the initial version.
</ResponseField>

<ResponseField name="data[].new_values" type="object">
  Field-keyed object of values after the change.
</ResponseField>

<ResponseField name="data[].source_data_date" type="string">
  ISO date the source office published this version, when known.
</ResponseField>

<ResponseField name="data[].office_code" type="string">
  Lowercase office code that produced the change.
</ResponseField>

<ResponseField name="data[].created_at" type="string">
  ISO 8601 timestamp when Signa observed and persisted the change.
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "version": 4,
        "change_type": "updated",
        "changed_fields": ["status_stage", "status_reason"],
        "old_values": { "status_stage": "examining", "status_reason": null },
        "new_values": { "status_stage": "registered", "status_reason": null },
        "source_data_date": "2025-08-12",
        "office_code": "uspto",
        "created_at": "2025-08-13T03:14:09Z"
      }
    ],
    "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/changes?changed_field=status_stage&limit=10" \
    -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 changes = await signa.trademarks.changes("tm_abc123", {
    changed_field: "status_stage",
    limit: 10,
  });

  for (const change of changes.data) {
    console.log(change.version, change.changed_fields);
  }
  ```
</CodeGroup>

## Errors

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

See [Errors](/api-reference/errors) for the full envelope.

## Related Endpoints

* [Trademark History](/api-reference/trademarks/trademark-history): office event timeline (filings, publications, decisions)
* [Get Trademark](/api-reference/trademarks/get-trademark): current full detail
* [Trademark Source](/api-reference/trademarks/trademark-source): raw source provenance for the latest version