{"openapi":"3.1.0","info":{"title":"Signa API","version":"1.0.0","description":"Global Trademark Intelligence Platform API — trademark search & intelligence across 11 production offices (USPTO, EUIPO, WIPO, CIPO, IP Australia, IPOS, UKIPO, INPI France, NIPO, PRV, IPI) with more in the pipeline."},"servers":[{"url":"https://api.signa.so","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Trademarks","description":"Retrieve and list trademark registrations and applications across offices"},{"name":"Owners","description":"Look up trademark owners (applicants/registrants) and their portfolios"},{"name":"Attorneys","description":"Look up attorneys/representatives of record and their portfolios"},{"name":"Firms","description":"Look up law firms and their attorneys, trademark portfolios, and performance stats"},{"name":"Proceedings","description":"Search and retrieve trademark proceedings (oppositions, cancellations, etc.)"},{"name":"Citations","description":"Examiner refusal citations — the prior marks an office cited against an application"},{"name":"Classification","description":"Browse free Nice classification and goods and services catalogs; metered class suggestions, wording drafts, and validation"},{"name":"Fees","description":"Verified official fee catalog and native-currency estimates"},{"name":"Deadlines","description":"List and compute trademark maintenance and prosecution deadlines from jurisdictional rules, with rule and trigger provenance; includes the deadline rule catalog"},{"name":"Oppositions","description":"Compute opposition windows from office publication rules; includes the opposition rule catalog"},{"name":"Reconciliation","description":"Compare caller-held trademark data against normalized register records"},{"name":"Reference Data","description":"Catalogs of trademark offices, jurisdictions, design codes, and event types — plus office-coverage voting, where an organization casts, lists, and retracts votes for the offices it wants covered"},{"name":"Portfolios","description":"Create and manage trademark portfolios (collections of marks)"},{"name":"Watches","description":"Saved monitors that fire alerts when matching trademarks change (TSK-111 monitoring v1)"},{"name":"Alerts","description":"Immutable alert rows produced by watch evaluation — read-only in v1"},{"name":"Webhooks","description":"Push delivery for alerts and sync events (Standard Webhooks signed)"},{"name":"Events","description":"Beta: per-organization event ledger and replay rail; payload contracts are versioned by `payload_version`; stability of the payload shape is not yet promised"},{"name":"Administration","description":"Organization identity, usage, logs, and API key management"},{"name":"Health","description":"Service health and readiness checks (unauthenticated)"}],"x-tagGroups":[{"name":"Data","tags":["Trademarks","Entities","Owners","Attorneys","Firms","Proceedings","Assignments","Citations"]},{"name":"Intelligence","tags":["Screening","Compare"]},{"name":"Filing & docketing","tags":["Classification","Deadlines","Oppositions","Fees","Reconciliation","Portfolios"]},{"name":"Monitoring","tags":["Watches","Alerts","Webhooks","Events"]},{"name":"Analytics","tags":["Analytics"]},{"name":"Reference","tags":["Reference Data"]},{"name":"Administration","tags":["Administration","Feedback","Health"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (sig_ prefix)"}},"schemas":{"OfficeRawValue":{"type":["object","null"],"properties":{"code":{"type":["string","null"],"description":"The office's verbatim code.","example":"800"},"label":{"type":["string","null"],"description":"The office's verbatim label; null when the office publishes none. Never rewritten (decode codes via GET /v1/status-codes).","example":"REGISTERED AND RENEWED"}},"required":["code","label"],"description":"The office's verbatim status code and label. Null on IR family rows (no single office status stands behind a rollup) and when the office published neither."},"TrademarkStatus":{"type":"object","properties":{"primary":{"type":"string","description":"pending|active|inactive|unknown, or \"mixed\" on IR family rows whose legs disagree (projection-only).","example":"active"},"stage":{"type":"string","description":"Granular status stage, or \"mixed\" on IR family rows whose legs disagree (projection-only).","example":"registered"},"reason":{"type":["string","null"]},"challenges":{"type":"array","items":{"type":"string"},"description":"Pending challenges against the record. On an IR family row, the de-duplicated union across its designations.","example":["opposition_pending"]},"effective_date":{"type":["string","null"],"description":"Office-reported date when the current status took effect, when available.","example":"2025-01-20"},"basis":{"type":"string","enum":["office","event_derived","dispatch_derived","computed"],"description":"How the normalised status was reached: `office` (the office stated it), `event_derived` (from the office's events), `dispatch_derived` (from an office dispatch), or `computed` (Signa's projection, e.g. an IR family rolled up from its legs).","example":"office"},"raw":{"$ref":"#/components/schemas/OfficeRawValue"}},"required":["primary","stage","reason","challenges","effective_date","basis","raw"]},"TrademarkRegister":{"type":["object","null"],"properties":{"type":{"type":["string","null"],"description":"The office's register (lowercased), e.g. principal / supplemental.","example":"principal"},"acquired_distinctiveness":{"type":["string","null"],"enum":["full","partial",null],"example":null},"is_incontestable":{"type":["boolean","null"],"example":false},"standard_characters_claimed":{"type":["boolean","null"],"example":true}},"required":["type","acquired_distinctiveness","is_incontestable","standard_characters_claimed"],"description":"The office register block; null when the office states no register data."},"TrademarkDesignCode":{"type":"object","properties":{"system":{"type":"string","enum":["vienna","us_design_search","other"],"example":"vienna"},"code":{"type":"string","example":"26.04.01"},"edition":{"type":["string","null"],"description":"Classification edition; null when the office states none.","example":"8"}},"required":["system","code","edition"]},"Address":{"type":["object","null"],"properties":{"lines":{"type":"array","items":{"type":"string"},"description":"The office's address lines, verbatim.","example":["One Bowerman Drive"]},"city":{"type":["string","null"],"example":"BEAVERTON"},"region":{"type":["string","null"],"description":"State, province or region, as the office supplied it.","example":"OR"},"postal_code":{"type":["string","null"],"example":"97005"},"country_code":{"type":["string","null"],"description":"ISO 3166-1 alpha-2, when the office supplied a code.","example":"US"},"formatted":{"type":["string","null"],"description":"The office's single-string rendering; null when it sent components only.","example":null}},"required":["lines","city","region","postal_code","country_code","formatted"]},"DerivedTerm":{"type":"object","properties":{"state":{"type":"string","enum":["in_term","in_grace","in_restoration","renewal_not_on_record","not_applicable"],"description":"Where the term on record stands at `as_of_date`. `in_term`: the term runs to `derived.expiry_date`, and its renewal is not past due (the due date itself, moved off a weekend or holiday, is still on time). `in_grace`: the term ended and the renewal can still be filed late, until `grace_expiry_date`. `in_restoration`: the grace period passed and the jurisdiction's restoration window is open, until `restoration_expiry_date`. `renewal_not_on_record`: the term end the office stated, its grace period and any restoration window have passed with no renewal of that term on record, so no later term is computed. For a US registration with no stated term end, also when its ten-year renewal (Section 8 and Section 9) is not on record once the grace period has passed, where Signa holds the USPTO prosecution history with a Section 8 or Section 9 filing recorded and the USPTO status does not say it was renewed. The mark may have lapsed, or a renewal may not have reached the office record or Signa yet; `status` stays what the office reports. `not_applicable`: no registered term to assess: an application or another status that is not registered (`unknown` included), a dead mark, a record with no renewal rule (a US designation under the Madrid Protocol, renewed at WIPO), or no schedule computed. An `expired` mark is assessed only while it can still be renewed or restored, a `cancelled` one only while it can be restored. Treat the vocabulary as open.","example":"in_term"},"grace_expiry_date":{"type":["string","null"],"description":"The last day of the grace period of the term ending at `derived.expiry_date`, as its renewal row serves it. Null when `state` is `not_applicable`.","example":"2035-07-20"},"restoration_expiry_date":{"type":["string","null"],"description":"The last day of the restoration window after that grace period, once the term has ended (`state` is `in_grace` or later), where the jurisdiction provides one (for example GB, EU, SG, JP, IN, IS) for a national registration. A Madrid designation has none: it renews only at WIPO. Null otherwise.","example":null},"renewed":{"type":"boolean","description":"Whether a renewal on record began the term ending at `derived.expiry_date`, that is, renewed the term before it: the office states a term end past the first term, the office recorded that renewal (for the USPTO, accepted the renewal filing), or, for a Madrid designation, WIPO published an expiry for the international registration in a later term. False for the first term after registration, for a term computed on the statutory ladder with no renewal of the term before it on record (a renewal of an earlier term does not count), and when `state` is `not_applicable`.","example":true}},"required":["state","grace_expiry_date","restoration_expiry_date","renewed"]},"UnsupportedDeadlineRule":{"type":"object","properties":{"rule_id":{"type":"string","description":"Slug of the declined rule. Same identity as `rule_id` on a computed row: join it to `GET /v1/deadline-rules` for the rule and its sources.","example":"ph_declaration_of_use_5yr_madrid"},"reason":{"type":"string","enum":["requires_office_date","computed_on_office_leg"],"description":"Why no row was computed for this rule. `requires_office_date`: the record lacks the date the statute anchors this rule on, and the law supports no fallback, so the engine declines instead of guessing. `computed_on_office_leg`: this record is WIPO's copy of a designation, and the rule runs from a date only the designated office's own record carries, so it is computed on that record instead. Today this is every US Madrid rule (Section 71 and Section 15) on a WIPO record designating the US: the dates come from the USPTO record of the designation, which carries the US registration date.","example":"requires_office_date"},"missing_field":{"type":"string","description":"The anchor the rule needs, in the `trigger_field` vocabulary of computed rows. `protection_grant_date` is the `protection_grant_date` compute input and the `protection_effective_date` of a stored trademark.","example":"protection_grant_date"},"consequence_if_missed":{"type":"string","description":"What happens if the obligation is missed. Same vocabulary as computed rows.","example":"removal_from_register"}},"required":["rule_id","reason","missing_field","consequence_if_missed"]},"DeadlineRow":{"type":"object","properties":{"occurrence_key":{"type":"string","description":"Stable identity of this occurrence of the rule, unique within one trademark: `rule_id:cycle` (the statutory cycle, e.g. `us_renewal_s9:5`), or `rule_id:t<term>-<n>` (a cell on a fixed term grid) when the record has no statutory anchor date or the row is anchored on an office-stated expiry; `rule_id:1` for a rule that occurs once; `rule_id:<action date>:<action code>` for a `post_registration_oa_response` row (one per office action, e.g. `uspto_post_registration_oa_response:2026-04-19:PRA8`). A renewal or a date correction of a few days keeps the key.","example":"us_renewal_s9:5"},"rule_id":{"type":"string","description":"Stable opaque slug of the statutory rule; the join key to `/v1/deadline-rules`. Do not parse it.","example":"us_renewal_s9"},"type":{"type":"string","description":"Deadline type: `renewal`, `declaration_of_use`, `combined_renewal_and_use`, `declaration_of_incontestability`, `restoration`, `international_renewal`, or `post_registration_oa_response` (USPTO: the response to a post-registration office action on a §8, §71 or §8+§9 filing, due six months from the action or at the end of the filing period, whichever is later; 37 CFR 2.163(b), 2.184(b)(1), 7.39(a)). New values may be added.","example":"combined_renewal_and_use"},"jurisdiction_code":{"type":"string","description":"Jurisdiction the row's rule applies in: `WO` for the international registration's own renewal; on a Madrid designation, the designated jurisdiction (`RU` on a Russian designation served `madrid_designation_renewal`).","example":"US"},"trigger_date":{"type":"string","example":"2025-01-20"},"trigger_field":{"type":"string","description":"Which record date anchored the computation (filing_date, registration_date, grant_date, protection_grant_date, intl_registration_date), reported_expiry / reported_renewal_due when the ladder is anchored on an office-stated date, or post_registration_action on a `post_registration_oa_response` row (the office action's date).","example":"registration_date"},"window_opens":{"type":"string","example":"2034-01-20"},"due_date":{"type":"string","example":"2035-01-22"},"due_date_adjustment":{"type":"string","enum":["moved","unchanged","not_checked","month_end_overflow"],"description":"What moved the due date off the plain statutory arithmetic: `moved` (the business-day roll changed it), `unchanged` (a calendar was consulted and the date was already a business day), `not_checked` (no pinned closure list verified this date: the rule has no calendar, or the date is outside the calendar's pinned coverage, where the deterministic weekend and fixed-holiday roll may still have been applied; the true date can only be the same or LATER), or `month_end_overflow` (the period ran into the following calendar month because its end day number does not exist in the target one, which is the Mexican rule; reported in place of `moved` or `unchanged` only when the business-day roll after the overflow was verified inside the calendar's pinned coverage, so an out-of-coverage overflowed date reports `not_checked` and still carries the overflow).","example":"moved"},"grace_expiry_date":{"type":"string","example":"2035-07-20"},"grace_expiry_adjustment":{"type":"string","enum":["moved","unchanged","not_checked","month_end_overflow"],"description":"Same vocabulary as `due_date_adjustment`, for the grace expiry. Evaluated independently, so the two can differ on one row.","example":"unchanged"},"holiday_calendar":{"type":["string","null"],"description":"Holiday calendar identifier this row’s dates were rolled against, or null when none applies. Usually the office’s configured calendar; `wipo_geneva` for a `madrid_only` renewal, whose period is the International Bureau’s.","example":"uspto_dc"},"is_recurring":{"type":"boolean"},"is_optional":{"type":"boolean","description":"True for filings that are advantageous but not required (e.g. US §15 incontestability)."},"consequence_if_missed":{"type":"string","example":"cancellation_and_expiration"},"note":{"type":"string","description":"Present only when the record or its rule adds something the dates do not say. On a `post_registration_oa_response` row: the office action it answers (code and date), and any incomplete-response notice or missing filing history; when the record cannot settle the date, the row is served on the earliest defensible date and the note says to check TSDR. A post-registration action marked \"no response required\" with no response row to carry it is said on every row of the record while its petition period can run. When the office prosecution history could not be read, every row of the record says so here instead of reading as checked. On a Madrid designation of Cabo Verde, Cambodia or Mozambique served `madrid_designation_renewal`, every row says the schedule is the renewal only: those offices also require use declarations filed with them, which are not computed.","example":"PRA8 2026-04-19"}},"required":["occurrence_key","rule_id","type","jurisdiction_code","trigger_date","trigger_field","window_opens","due_date","due_date_adjustment","grace_expiry_date","grace_expiry_adjustment","holiday_calendar","is_recurring","is_optional","consequence_if_missed"]},"DerivedOppositionWindow":{"anyOf":[{"type":"object","properties":{"supported":{"type":"boolean","enum":[true]},"reason":{"type":"null"},"rule_id":{"type":"string","description":"Join key to `/v1/opposition-rules`.","example":"us_opposition"},"trigger_event":{"type":"string","enum":["application_publication","registration_publication","international_designation_publication"],"example":"application_publication"},"publication_date":{"type":"string","example":"2024-11-05"},"window_opens":{"type":"string","example":"2024-11-06"},"window_closes":{"type":"string","example":"2024-12-05"},"close_adjustment":{"type":"string","enum":["moved","unchanged","not_checked","month_end_overflow"],"description":"Whether `window_closes` was checked against the office's holiday calendar. `not_checked`: no pinned closure list verified it, so the close is correct-or-EARLY and indeterminate near today.","example":"unchanged"},"office_time_zone":{"type":"string","example":"America/New_York"},"common_extension":{"type":["object","null"],"properties":{"days":{"type":["integer","null"]},"months":{"type":["integer","null"]},"as_of_right":{"type":"boolean"},"notes":{"type":"string"}},"required":["days","months","as_of_right","notes"]}},"required":["supported","reason","rule_id","trigger_event","publication_date","window_opens","window_closes","close_adjustment","office_time_zone","common_extension"]},{"type":"object","properties":{"supported":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["unsupported_office","requires_office_date","publication_date_kind_mismatch","stage_not_opposable"],"description":"`unsupported_office`: no opposition rule is modeled. `requires_office_date`: no publication date. `publication_date_kind_mismatch`: the stored publication is not the one the matched Madrid rule runs from. `stage_not_opposable`: the mark is past the stage it can be opposed at.","example":"stage_not_opposable"},"rule_id":{"type":["string","null"],"example":"us_opposition"}},"required":["supported","reason","rule_id"]}]},"DerivedBlock":{"type":"object","properties":{"ruleset_version":{"type":"string","description":"Content hash of the rule set that produced this block.","example":"rs_3f2a9c1b7e40"},"as_of_date":{"type":"string","description":"The date the block was computed for.","example":"2026-09-26"},"expiry_date":{"type":["string","null"],"description":"The end of the term on record, before any weekend or holiday roll. Where the office publishes the expiry it is that date, moved forward only by a renewal on record: one the office recorded, or for a Madrid designation an expiry WIPO published for the international registration in a later term. Where the office publishes none (the USPTO) it is the statutory term end. Once an office-stated term has ended it stays here; `term.state` says whether it can still be renewed or restored, or that no renewal of it is on record. Null when no term applies (a dead mark once it can no longer be saved, a record with no renewal rule, or no schedule).","example":"2035-01-20"},"term":{"$ref":"#/components/schemas/DerivedTerm"},"deadlines":{"type":"object","properties":{"supported":{"type":"boolean","description":"False when no schedule could be computed; see `reason`. Mirrors POST /v1/deadlines/compute."},"reason":{"type":["string","null"],"enum":["unsupported_jurisdiction","requires_office_date",null],"description":"Why no schedule was computed. `unsupported_jurisdiction`: no rules are modeled for the jurisdiction. `requires_office_date`: the record lacks the input the statute needs and the office stated no expiry to anchor on."},"unsupported_rules":{"type":"array","items":{"$ref":"#/components/schemas/UnsupportedDeadlineRule"},"description":"Rules that apply but were declined because the record lacks the date the statute anchors them on, so `items` has no row for them. `[]` when nothing was declined and when `supported` is false."},"items":{"type":"array","items":{"$ref":"#/components/schemas/DeadlineRow"},"description":"The computed maintenance schedule in due-date order, ties by rule_id, within a 20-year horizon of `as_of_date`. Empty for dead marks and unsupported records."}},"required":["supported","reason","unsupported_rules","items"]},"next_deadline":{"anyOf":[{"$ref":"#/components/schemas/DeadlineRow"},{"type":"null"}],"description":"The earliest row of `deadlines.items` whose grace period has not passed; on a same-day tie a mandatory row wins over an optional one such as the US §15 affidavit. Null when none."},"opposition_window":{"$ref":"#/components/schemas/DerivedOppositionWindow"}},"required":["ruleset_version","as_of_date","expiry_date","term","deadlines","next_deadline","opposition_window"]},"SourceRecordRef":{"type":"object","properties":{"source_office_code":{"type":["string","null"],"example":"WO"},"territory_code":{"type":["string","null"],"example":"US"},"trademark":{"type":"object","properties":{"id":{"type":"string","example":"tm_7d4e1f2a-3b8c-4d0e-9f1a-2b3c4d5e6f70"},"href":{"type":"string","example":"/v1/trademarks/tm_7d4e1f2a-3b8c-4d0e-9f1a-2b3c4d5e6f70"}},"required":["id","href"]}},"required":["source_office_code","territory_code","trademark"]},"CoverageTerritory":{"type":"object","properties":{"territory_code":{"type":"string","example":"US"},"status":{"type":"object","properties":{"primary":{"type":"string","example":"active"},"stage":{"type":"string","example":"registered"}},"required":["primary","stage"]},"protection_status":{"type":["string","null"],"example":"protected"},"designation_date":{"type":["string","null"],"example":"2024-06-01"},"protection_date":{"type":["string","null"],"example":"2025-01-20"},"publication_date":{"type":["string","null"],"description":"Date the WIPO Gazette published this designation; null when Signa has no Gazette date for it. Not the national journal date an office may run opposition from.","example":"2024-07-04"},"office_url":{"type":["string","null"],"description":"The designation record's office permalink; null when none is stored.","example":null},"trademark":{"type":["object","null"],"properties":{"id":{"type":"string","example":"tm_7d4e1f2a-3b8c-4d0e-9f1a-2b3c4d5e6f70"},"href":{"type":"string","example":"/v1/trademarks/tm_7d4e1f2a-3b8c-4d0e-9f1a-2b3c4d5e6f70"}},"required":["id","href"],"description":"The representative record for this territory. Null only when the record could not be resolved."},"office_code":{"type":["string","null"],"description":"WIPO ST.3 code of the office that holds the designation record shown for this territory (the national office when Signa has its record, else WO).","example":"US"},"application_number":{"type":["string","null"],"description":"That record's own application number at its office (for a US designation, the 79-series serial); null when the office states none.","example":"79415041"},"registration_number":{"type":["string","null"],"description":"That record's own registration number at its office; null until registered or when the office states none.","example":"7000001"}},"required":["territory_code","status","protection_status","designation_date","protection_date","publication_date","office_url","trademark","office_code","application_number","registration_number"]},"DetailCoverageTerritory":{"allOf":[{"$ref":"#/components/schemas/CoverageTerritory"},{"type":"object","properties":{"territory_name":{"type":["string","null"],"example":"United States of America"},"refusal_date":{"type":["string","null"],"example":"2025-03-11"},"status_effective_date":{"type":["string","null"],"example":"2025-06-01"},"is_subsequent_designation":{"type":["boolean","null"],"example":false},"designation_protocol":{"type":["string","null"],"example":"madrid_protocol"},"source_records":{"type":"array","items":{"$ref":"#/components/schemas/SourceRecordRef"},"description":"Reconciliation alternates for a dual-feed territory (the WIPO-feed record folded into a winning national-feed record, or vice versa). Empty for a single-feed territory."}},"required":["territory_name","refusal_date","status_effective_date","is_subsequent_designation","designation_protocol","source_records"]}]},"GroupedCoverage":{"type":"object","properties":{"territory_count":{"type":"integer","example":50},"by_primary":{"type":"object","additionalProperties":{"type":"integer"},"example":{"active":46,"pending":2,"inactive":2}},"by_stage":{"type":"object","additionalProperties":{"type":"integer"},"example":{"registered":46,"pending":2,"refused":2}},"matched_territories":{"type":"array","items":{"type":"string"},"description":"Non-empty when a territory/status filter narrowed the result; always [] on detail.","example":[]},"territories":{"type":"array","items":{"$ref":"#/components/schemas/CoverageTerritory"}}},"required":["territory_count","by_primary","by_stage","matched_territories","territories"]},"DetailCoverage":{"allOf":[{"$ref":"#/components/schemas/GroupedCoverage"},{"type":"object","properties":{"territories":{"type":"array","items":{"$ref":"#/components/schemas/DetailCoverageTerritory"}}}}],"description":"IR family rows only: per-territory coverage with per-designation detail."},"TrademarkRelationship":{"type":"object","properties":{"type":{"type":"string","example":"based_on_basic_registration"},"direction":{"type":"string","enum":["child","parent"],"example":"child"},"trademark_id":{"type":["string","null"],"example":"tm_7d4e1f2a-3b8c-4d0e-9f1a-2b3c4d5e6f70"},"target_office_code":{"type":["string","null"],"description":"ST.3 office code of the counterpart as reported by the office. Null on `parent` edges (the counterpart is identified by `trademark_id`).","example":"US"},"target_record_id":{"type":["string","null"],"description":"Office-native identifier of the counterpart. Null on `parent` edges (the counterpart is identified by `trademark_id`).","example":"97123456"},"office_code":{"type":["string","null"],"example":"US"},"mark_text":{"type":["string","null"],"example":"SIGNA"},"status_stage":{"type":["string","null"],"example":"registered"},"effective_date":{"type":["string","null"],"example":"2024-03-15"}},"required":["type","direction","trademark_id","target_office_code","target_record_id","office_code","mark_text","status_stage","effective_date"]},"Provenance":{"type":"object","properties":{"source_data_date":{"type":["string","null"],"description":"Date of the office data file/response this record was built from.","example":"2026-03-18"},"snapshot_date":{"type":["string","null"],"description":"Date of the office's bulk snapshot this record was last seen in, when the office publishes snapshots (e.g. a USPTO daily file). Null otherwise.","example":"2026-03-17"},"office_updated_at":{"type":["string","null"],"description":"The office's own last-modified timestamp for the record, when it publishes one.","example":"2026-03-17T00:00:00Z"},"retrieved_at":{"type":["string","null"],"description":"When Signa last fetched the full detail record from the office.","example":"2026-03-18T04:00:00Z"}},"required":["source_data_date","snapshot_date","office_updated_at","retrieved_at"]},"TrademarkDetailV1":{"type":"object","properties":{"id":{"type":"string","example":"tm_7d4e1f2a3b8c9d0e"},"object":{"type":"string","enum":["trademark"]},"grain":{"type":"string","enum":["mark","record"],"description":"Which unit this row is: a mark (a standalone filing, or an IR family rolled up from its legs) or a single trademark record (a Madrid designation leg of an IR family on file, or any row of an `international_registrations=expanded` search; an unlinked designation is a standalone mark). Family-only fields (`coverage`, `source_records`, `owners_mixed`) appear only on IR family rows.","example":"mark"},"mark_text":{"type":["string","null"],"example":"SIGNA"},"mark_feature_type":{"type":["string","null"],"example":"word"},"mark_legal_category":{"type":["string","null"],"example":"standard"},"right_kind":{"type":"string","example":"trademark"},"status":{"$ref":"#/components/schemas/TrademarkStatus"},"office_code":{"type":["string","null"],"example":"US"},"jurisdiction_code":{"type":["string","null"],"example":"US"},"scope_kind":{"type":"string","example":"national"},"filing_route":{"type":"string","example":"direct_national"},"origin_office_code":{"type":["string","null"],"description":"Origin office code for Madrid records. Null for non-Madrid marks.","example":"JP"},"office_record_id":{"type":["string","null"],"description":"The office's own identifier for the record. Null only when Signa composed the stored key (an IR's own record and its WIPO-feed, Finnish and Polish designation records); other national-office records of a designation keep the office's id.","example":"97123456"},"office_url":{"type":["string","null"],"description":"The office permalink for the record; null when none is stored.","example":"https://tsdr.uspto.gov/#caseNumber=97123456"},"application_number":{"type":["string","null"],"example":"97123456"},"registration_number":{"type":["string","null"],"description":"The registration number as the office publishes it (an IR number without any prefix).","example":"6789012"},"ir_number":{"type":["string","null"],"description":"Madrid International Registration number, without leading zeros (`551089`, not the `0551089` some offices store), so a designation and its international registration carry the same value. Null for non-Madrid marks.","example":"1234567"},"designation_date":{"type":["string","null"],"description":"Madrid designation date for designation legs. Null for non-Madrid marks.","example":"2024-06-01"},"filing_date":{"type":["string","null"],"example":"2024-03-15"},"registration_date":{"type":["string","null"],"example":"2025-01-20"},"expiry_date":{"type":["string","null"],"description":"The expiry date the office published; null when it published none (the rulebook value is `derived.expiry_date`).","example":"2035-01-20"},"renewal_due_date":{"type":["string","null"],"description":"The renewal due date the office published; null when it published none.","example":"2035-01-20"},"last_renewal_date":{"type":["string","null"],"description":"The date of the last renewal the office recorded; null when it published none.","example":"2025-01-20"},"publication_date":{"type":["string","null"],"description":"First publication date when available. On an international registration (filing_route madrid_ir), the earliest WIPO Gazette publication across its designations: a derived date, not the national journal date an office may run opposition from.","example":"2024-11-05"},"termination_date":{"type":["string","null"],"example":"2026-02-01"},"priority_date":{"type":["string","null"],"example":"2024-01-15"},"register":{"$ref":"#/components/schemas/TrademarkRegister"},"classifications":{"type":"array","items":{"type":"object","properties":{"nice_class":{"type":["integer","null"],"description":"The Nice class number; null when the office states the goods/services without a class.","example":9},"goods_services_text":{"type":["string","null"],"example":"Computer software for trademark intelligence"},"goods_services_text_truncated":{"type":"boolean","description":"True when goods_services_text was shortened in a summary/list row. Use include=full_goods_services or fetch detail for the full text. Always false on detail.","example":false},"scope":{"type":"string","enum":["as_filed"],"description":"Classification scope on IR family rows: as filed, NOT territory-effective. Absent on other rows.","example":"as_filed"},"nice_edition":{"type":["string","null"],"example":"12"},"goods_services_language":{"type":["string","null"],"example":"en"},"status":{"type":["string","null"],"example":"accepted"},"status_raw":{"allOf":[{"$ref":"#/components/schemas/OfficeRawValue"},{"description":"The office's verbatim class status. Null when the office states none."}]},"subclass_codes":{"type":["array","null"],"items":{"type":"string"},"description":"Office-native subclass codes when the office reports them; null when not provided.","example":["A","B"]},"goods_services_binding":{"type":["string","null"],"enum":["class","record",null],"description":"How goods_services_text belongs to this class. `class`: the text is this class's own (the office states it for this class, or the record has no other class of its kind). `record`: the office states the text for the record's goods (or services) without saying which class it belongs to, and the record has several goods (or services) classes, so the text is repeated on each of them and part of it may describe another. Some older Canadian (CIPO) filings state their goods and services this way. Null when the row has no text, or when the binding is unknown: Signa sets it only from the office's own goods and services statements, kept so far for reprocessed Canadian (CIPO) records, so it is null on every other record.","example":"class"},"office_class":{"type":["string","null"],"description":"The class as the office states it. Usually the Nice class in the office's own spelling. A row with no Nice class says here what it is: US `A` (certification mark for goods), `B` (certification mark for services) or `200` (collective membership mark), or Spain's `00`. null on an international registration's classes rolled up from its designations.","example":"009"}},"required":["nice_class","goods_services_text","goods_services_text_truncated","nice_edition","goods_services_language","status","status_raw","subclass_codes","goods_services_binding","office_class"]}},"nice_classes":{"type":"array","items":{"type":"integer","minimum":1,"maximum":45},"description":"Compact Nice class numbers derived from classifications[].nice_class.","example":[9,42]},"design_codes":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkDesignCode"}},"owners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"own_abc123"},"name":{"type":"string","description":"The name as filed on this record.","example":"Signa Technologies Inc."},"country_code":{"type":["string","null"],"example":"US"},"legal_form":{"type":["string","null"],"description":"The kind of legal person, normalised from the office's entity-type code; null when the office states none.","example":"corporation"},"entity_id":{"type":["string","null"],"description":"The entity linker's relationship: the resolved entity this owner belongs to. Null when the owner is not linked to an entity.","example":"ent_abc123"},"companies":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["sec","gleif"],"example":"sec"},"ticker":{"type":["string","null"],"example":"AAPL"},"exchange":{"type":["string","null"],"example":"NASDAQ"},"lei":{"type":["string","null"],"example":"7LTWFZYICNSX8D621K86"},"entity_status":{"type":"string","enum":["active","inactive","delisted"],"example":"active"}},"required":["source","ticker","exchange","lei","entity_status"]},"description":"Public company records linked to this owner. Absent when none."},"role":{"type":"string","example":"owner"},"is_current":{"type":"boolean","description":"Whether the office lists this party as a current owner. Detail lists current owners only.","example":true},"address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","country_code","legal_form","entity_id","role","is_current","address"]}},"has_media":{"type":"boolean"},"primary_image_url":{"type":["string","null"],"description":"Media-proxy URL for the primary mark image: the office-flagged image, else the first image. Always an image file, never a document, audio or video file. Null when the mark has no image.","example":"https://api.signa.so/v1/trademarks/tm_abc/media/01234567-89ab-cdef-0123-456789abcdef"},"derived":{"$ref":"#/components/schemas/DerivedBlock"},"updated_at":{"type":"string","example":"2026-03-18T04:00:00Z"},"coverage":{"$ref":"#/components/schemas/DetailCoverage"},"source_records":{"type":"array","items":{"$ref":"#/components/schemas/SourceRecordRef"},"description":"IR family rows only: WIPO/national reconciliation alternates (§12.1)."},"owners_mixed":{"type":"boolean","description":"IR family rows only: true when the legs' current owners resolve to more than one holder."},"mark_text_language":{"type":["string","null"],"example":"en"},"mark_text_script":{"type":["string","null"]},"is_series_mark":{"type":["boolean","null"]},"series_count":{"type":["integer","null"]},"protection_effective_date":{"type":["string","null"]},"dependency_period_end_date":{"type":["string","null"]},"transformation_deadline_date":{"type":["string","null"]},"is_retracted":{"type":"boolean"},"attorneys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"att_def456"},"name":{"type":"string","description":"The name as filed on this record.","example":"Jane Smith"},"firm_id":{"type":["string","null"],"description":"The firm this filing names. Null when the filing names no firm; never a firm taken from the attorney's other filings.","example":"firm_ghi789"},"firm_name":{"type":["string","null"],"description":"The firm name as filed on this record when stated, else the name of the `firm_id` firm. Null when the filing names no firm.","example":"Smith & Associates LLP"},"role":{"type":"string","example":"representative"},"address":{"$ref":"#/components/schemas/Address"},"territory_codes":{"type":"array","items":{"type":"string"},"description":"On a Madrid international registration row (one row per attorney and firm): the designated territories whose record names this attorney with this firm, sorted. Empty when only the international registration itself names the attorney. Absent on other rows.","example":["EU","US"]}},"required":["id","name","firm_id","firm_name","role","address"]}},"text_variants":{"type":"array","items":{"type":"object","properties":{"variant_type":{"type":"string","example":"translation"},"text":{"type":"string","example":"Marque commerciale"},"language_code":{"type":["string","null"],"example":"fr"},"script_code":{"type":["string","null"]},"is_display_preferred":{"type":"boolean"}},"required":["variant_type","text","language_code","script_code","is_display_preferred"]}},"statements":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"disclaimer"},"text":{"type":"string"},"language_code":{"type":["string","null"],"example":"en"},"applies_to_class":{"type":["integer","null"]}},"required":["type","text","language_code","applies_to_class"]}},"media":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"media_type":{"type":"string","example":"image"},"mime_type":{"type":["string","null"],"example":"image/jpeg"},"url":{"type":"string"},"is_primary":{"type":"boolean","description":"Exactly one item is primary when `primary_image_url` is set: the item that URL points at."},"document_kind":{"type":["string","null"],"description":"Signa's classification of the office's document type for a document item (office_action, certificate, correspondence, filed_form, other), the same value `GET /v1/trademarks/{id}/documents` serves; null for images.","example":"office_action"},"official_date":{"type":["string","null"],"description":"The office's date on the document (mailing or issue date), as published; null when none.","example":"2025-02-03"},"page_count":{"type":["integer","null"],"description":"Page count of a document item, as published by the office; null when none.","example":4}},"required":["id","media_type","mime_type","url","is_primary","document_kind","official_date","page_count"]}},"priority_claims":{"type":"array","items":{"type":"object","properties":{"priority_type":{"type":"string","example":"paris"},"country_code":{"type":["string","null"],"example":"GB"},"application_number":{"type":["string","null"]},"priority_date":{"type":["string","null"],"example":"2024-01-15"},"exhibition_name":{"type":["string","null"]}},"required":["priority_type","country_code","application_number","priority_date","exhibition_name"]}},"filing_bases":{"type":"array","items":{"type":"object","properties":{"basis_type":{"type":"string","example":"use_in_commerce"},"nice_class":{"type":["integer","null"]},"first_use_date":{"type":["string","null"]},"first_use_in_commerce_date":{"type":["string","null"]},"foreign_application_number":{"type":["string","null"]},"foreign_country_code":{"type":["string","null"]}},"required":["basis_type","nice_class","first_use_date","first_use_in_commerce_date","foreign_application_number","foreign_country_code"]}},"publications":{"type":"array","items":{"type":"object","properties":{"publication_type":{"type":["string","null"],"example":"opposition_notice"},"publication_date":{"type":["string","null"]},"bulletin_number":{"type":["string","null"]},"source_reference":{"type":["string","null"]},"opposition_period_start":{"type":["string","null"]},"opposition_period_end":{"type":["string","null"]}},"required":["publication_type","publication_date","bulletin_number","source_reference","opposition_period_start","opposition_period_end"]}},"office_extensions":{"type":"object","additionalProperties":{},"description":"Raw office-specific extension data. Returned only when include=office_extensions is requested."},"seniority_claims":{"type":"array","items":{"type":"object","properties":{"country_code":{"type":["string","null"],"example":"ES"},"registration_number":{"type":["string","null"],"example":"M1234567"},"kind":{"type":["string","null"],"example":"national"},"status":{"type":["string","null"],"enum":["claimed","accepted","refused","partially_refused","abandoned","deficiency",null],"example":"accepted"},"effective_date":{"type":["string","null"],"example":"2018-05-01"}},"required":["country_code","registration_number","kind","status","effective_date"]}},"relationships":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkRelationship"},"description":"Mark-to-mark relationships. Excludes Madrid designations (see coverage.territories[]) and seniority claims (see seniority_claims[]). Capped at 200 per mark."},"events_count":{"type":"integer"},"proceedings_count":{"type":"object","properties":{"contested":{"type":"integer","example":1},"asserted":{"type":"integer","example":40}},"required":["contested","asserted"],"description":"Proceedings linked to this mark, split by the mark's side (see GET /v1/trademarks/{id}/proceedings and its `trademark_role` filter). `contested`: proceedings filed against this mark (it was opposed, petitioned for cancellation, or appealed). `asserted`: proceedings its owner filed using this mark as a prior right. Both keys are always present; `0` and `0` means no proceedings."},"citations_count":{"type":["integer","null"],"description":"Office-action citations issued against this mark's application (see GET /v1/trademarks/{id}/citations). `0` means the office IS covered and this mark has no citations; `null` means no count is computed for this office at all — the two are never interchangeable. Check `capabilities.citations` on GET /v1/offices to see which offices produce a number (`available`) and which produce `null` (`not_available`, `in_progress`, `not_applicable`). A `null` count is not a promise of an empty list: while a new office is being brought online, GET /v1/trademarks/{id}/citations can already return rows for a mark whose `citations_count` is still `null`. Read `null` as \"not counted for this office\" and use the citations endpoint for the authoritative list. Always present on every full-detail response, including the batch lookup surface.","example":3},"provenance":{"$ref":"#/components/schemas/Provenance"},"created_at":{"type":"string","example":"2024-03-16T00:00:00Z"}},"required":["id","object","grain","mark_text","mark_feature_type","mark_legal_category","right_kind","status","office_code","jurisdiction_code","scope_kind","filing_route","origin_office_code","office_record_id","office_url","application_number","registration_number","ir_number","designation_date","filing_date","registration_date","expiry_date","renewal_due_date","last_renewal_date","publication_date","termination_date","priority_date","register","classifications","nice_classes","design_codes","owners","has_media","primary_image_url","derived","updated_at","mark_text_language","mark_text_script","is_series_mark","series_count","protection_effective_date","dependency_period_end_date","transformation_deadline_date","is_retracted","attorneys","text_variants","statements","media","priority_claims","filing_bases","publications","seniority_claims","relationships","events_count","proceedings_count","citations_count","provenance","created_at"]},"Trademark":{"allOf":[{"$ref":"#/components/schemas/TrademarkDetailV1"},{"type":"object","properties":{}}]},"ScreeningCoverage":{"type":"object","properties":{"classes":{"type":"object","properties":{"requested":{"type":"array","items":{"type":"integer"}},"resolved":{"type":"array","items":{"type":"integer"}},"expanded":{"type":"array","items":{"type":"integer"}},"searched":{"type":"array","items":{"type":"integer"}},"source":{"type":"string","enum":["requested","inferred","expanded"]},"inference_confidence":{"type":["string","null"],"enum":["high","medium","low",null]}},"required":["requested","resolved","expanded","searched","source","inference_confidence"],"description":"`requested` echoes the caller's `nice_classes`. `resolved` lists the classes the resolver matched from `nice_classes` plus `goods_services` (the record's classes on a `trademark_id` screen that sends neither). `searched` is the class filter applied by the class-filtered retrieval lanes, which can include classes matched from `goods_services`; the containment lane (marks that contain the name) is not class-filtered and searches every class. `expanded` lists the classes `searched` adds beyond `requested` (or, without `nice_classes`, beyond the record's or the inferred classes). A `trademark_id` screen sent without `nice_classes` or `goods_services` searches the record's classes: `requested` is [], `resolved` and `searched` hold the record's classes, and `source` reads `requested` (there is no record-specific source value)."},"offices":{"type":"array","items":{"type":"object","properties":{"office":{"type":"string"},"status":{"type":"string","enum":["complete","partial","stale","unavailable"]},"as_of":{"type":["string","null"]}},"required":["office","status","as_of"]}},"territories":{"type":"array","items":{"type":"object","properties":{"territory":{"type":"string","description":"Requested territory (EM→EU normalized).","example":"DE"},"national_register":{"type":"object","properties":{"office":{"type":["string","null"],"description":"Public (ST.3) office code of the territory's national register, or null when unmodeled.","example":"DE"},"covered":{"type":"boolean"}},"required":["office","covered"]},"regional_registers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"EU"},"covered":{"type":"boolean"}},"required":["code","covered"]}},"member_registers":{"type":"object","properties":{"total":{"type":"integer","example":27},"uncovered":{"type":"array","items":{"type":"string"},"description":"Member territories whose national register is not covered.","example":["DE","IT"]}},"required":["total","uncovered"],"description":"Present only for a REGIONAL request (jurisdictions=EU/BX/OA): a regional screen expands to member states, so completeness requires every member national register to be covered too."},"complete":{"type":"boolean","description":"True iff the full protecting register set is covered live+fresh: national + covering regional (country request), or the region's own register + every member national register (regional request)."}},"required":["territory","national_register","regional_registers","complete"]},"description":"Per-requested-territory protection-scope register coverage. Empty for offices-scoped and unscoped requests (which gate on the offices axis)."},"lanes":{"type":"object","properties":{"planned":{"type":"array","items":{"type":"string"}},"completed":{"type":"array","items":{"type":"string"}},"capped":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"string"}}},"required":["planned","completed","capped","failed"],"description":"Reserved. Per-lane status is not reported yet, so every list is empty."},"language":{"type":"object","properties":{"detected":{"type":["string","null"],"description":"Main script of the mark's letters: latin, cyrillic, cjk, thai, arabic or other. Null when the mark has no letters.","example":"latin"},"supported":{"type":"boolean","description":"False when the non-Latin letters outnumber the Latin letters (Unicode Latin script, all other scripts counted together). Screening matches Latin text, so an unsupported mark is never `clear`: a would-be clear becomes `needs_review` with the `unsupported_language` warning."}},"required":["detected","supported"]},"horizon":{"type":"object","properties":{"analyzed":{"type":"integer","description":"Conflicts banded within the analysis horizon."},"cap":{"type":"integer","description":"Most conflicts one screen analyses.","example":200},"capped":{"type":"boolean","description":"True when the overall horizon or a retrieval lane quota had more matches than it could analyse, so some were not analysed. Can be true with `analyzed` below `cap`."},"cap_reason":{"type":["string","null"]}},"required":["analyzed","cap","capped","cap_reason"]},"complete_for_clear":{"type":"boolean"}},"required":["classes","offices","territories","lanes","language","horizon","complete_for_clear"]},"ScreeningMetaV3":{"type":"object","properties":{"verdict":{"type":"string","enum":["high_risk","caution","needs_review","clear"]},"band_source":{"type":"string","enum":["v1_table","v3_scorer"]},"summary":{"type":"object","properties":{"high":{"type":"integer","minimum":0},"medium":{"type":"integer","minimum":0},"borderline":{"type":"integer","minimum":0},"low":{"type":"integer","minimum":0},"truncated":{"type":"boolean"}},"required":["high","medium","borderline","low","truncated"]},"litigation_risk":{"type":"object","properties":{"high":{"type":"integer","minimum":0},"medium":{"type":"integer","minimum":0}},"required":["high","medium"]},"candidate":{"type":"object","properties":{"mark":{"type":"string"},"normalized":{"type":"string"}},"required":["mark","normalized"]},"coverage":{"$ref":"#/components/schemas/ScreeningCoverage"},"clear_blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["analysis_horizon_capped","lane_failed","unsupported_language","stale_office_corpus","incomplete_office_coverage","low_confidence_class_inference"]},"message":{"type":"string"}},"required":["code","message"]}},"inferred_nice_classes":{"type":"array","items":{"type":"integer"}},"model_assessment":{"type":"object","properties":{"band":{"type":"string","enum":["high","medium","borderline","low"]},"confidence":{"type":"string","enum":["high","medium","low"]},"band_source":{"type":"string","enum":["v1_table","v3_scorer"]}},"required":["band","confidence","band_source"]},"rules_version":{"type":"string"},"as_of":{"type":["string","null"]},"admitted_match_levels":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string","enum":["no_goods_services","analysis_horizon_capped"]}},"note":{"type":"string"}},"required":["verdict","band_source","summary","litigation_risk","candidate","coverage","clear_blockers","rules_version","as_of","admitted_match_levels","warnings"]},"ScreeningFactorEntry":{"type":"object","properties":{"factor_id":{"type":"string"},"dupont_factor":{"type":"integer"},"assessment":{"type":"string"},"confidence":{"type":"string"},"evidence":{"type":"array","items":{"type":"object","additionalProperties":{}}},"limitations":{"type":"array","items":{"type":"string"}},"computed_by":{"type":"string"},"version":{"type":"string"}},"required":["factor_id","dupont_factor","assessment","confidence","evidence","limitations","computed_by","version"]},"TerritoryMatch":{"type":"object","properties":{"requested":{"type":"string","description":"The jurisdictions code the caller requested.","example":"FR"},"matched_via":{"type":"string","description":"The stored territory the hit matched on (WIPO's EM is rendered EU).","example":"EU"},"matched_via_kind":{"type":"string","enum":["direct","regional_membership"],"example":"regional_membership"}},"required":["requested","matched_via","matched_via_kind"]},"TrademarkMatch":{"type":"object","properties":{"tier":{"type":["string","null"],"enum":["identical","near_identical","similar","related",null],"description":"The strongest similarity tier of the lanes this hit matched: identical, near_identical, similar or related. Tiers are retrieval categories, not measured edit distances. Null for rows matched only by a trademark number in q, and for rows of a request without q.","example":"near_identical"},"via":{"type":"array","items":{"type":"string","enum":["identifier","identical","fuzzy","embedded","phonetic","lookalike"]},"description":"The similarity channels that matched this hit, plus `identifier` when q was read as a trademark number. Empty without q.","example":["fuzzy"]},"terms":{"type":"array","items":{"type":"string"},"description":"With a q list: the q terms that reached this hit, in list order, as the caller spelled them. Otherwise the mark_text operator values this hit satisfied (operator order: is, word, starts_with, ends_with, contains, pattern). Empty when the request has neither.","example":[]},"details":{"type":"object","properties":{"lanes":{"type":"array","items":{"type":"string"},"description":"Internal retrieval lane names that matched.","example":["fuzzy_1","phonetic_strong"]},"factors":{"type":"array","items":{"type":"object","properties":{"factor":{"type":"string","example":"live_status"},"weight":{"type":"number","example":1.3}},"required":["factor","weight"]},"description":"The ranking factors applied to this hit's score. Under an explicit sort, a trademark-number q or a q list the length factor does not apply."},"terms":{"type":"array","items":{"type":"object","properties":{"term":{"type":"string","example":"onyx"},"tier":{"type":["string","null"],"enum":["identical","near_identical","similar","related",null],"example":"identical"},"via":{"type":"array","items":{"type":"string","enum":["identifier","identical","fuzzy","embedded","phonetic","lookalike"]},"example":["lookalike"]}},"required":["term","tier","via"]},"description":"With a q list: each term that reached this hit, with its own tier and channels."}},"required":["lanes","factors"],"description":"Only with include=match_details."}},"required":["tier","via","terms"],"description":"Why the hit is in the result set. Search responses only; on a metadata-only listing (no q, no positive mark_text operator) tier is null and via and terms are empty."},"TrademarkSummaryV1":{"type":"object","properties":{"id":{"type":"string","example":"tm_7d4e1f2a3b8c9d0e"},"object":{"type":"string","enum":["trademark"]},"grain":{"type":"string","enum":["mark","record"],"description":"Which unit this row is: a mark (a standalone filing, or an IR family rolled up from its legs) or a single trademark record (a Madrid designation leg of an IR family on file, or any row of an `international_registrations=expanded` search; an unlinked designation is a standalone mark). Family-only fields (`coverage`, `source_records`, `owners_mixed`) appear only on IR family rows.","example":"mark"},"mark_text":{"type":["string","null"],"example":"SIGNA"},"mark_feature_type":{"type":["string","null"],"example":"word"},"mark_legal_category":{"type":["string","null"],"example":"standard"},"right_kind":{"type":"string","example":"trademark"},"status":{"$ref":"#/components/schemas/TrademarkStatus"},"office_code":{"type":["string","null"],"example":"US"},"jurisdiction_code":{"type":["string","null"],"example":"US"},"scope_kind":{"type":"string","example":"national"},"filing_route":{"type":"string","example":"direct_national"},"origin_office_code":{"type":["string","null"],"description":"Origin office code for Madrid records. Null for non-Madrid marks.","example":"JP"},"office_record_id":{"type":["string","null"],"description":"The office's own identifier for the record. Null only when Signa composed the stored key (an IR's own record and its WIPO-feed, Finnish and Polish designation records); other national-office records of a designation keep the office's id.","example":"97123456"},"office_url":{"type":["string","null"],"description":"The office permalink for the record; null when none is stored.","example":"https://tsdr.uspto.gov/#caseNumber=97123456"},"application_number":{"type":["string","null"],"example":"97123456"},"registration_number":{"type":["string","null"],"description":"The registration number as the office publishes it (an IR number without any prefix).","example":"6789012"},"ir_number":{"type":["string","null"],"description":"Madrid International Registration number, without leading zeros (`551089`, not the `0551089` some offices store), so a designation and its international registration carry the same value. Null for non-Madrid marks.","example":"1234567"},"designation_date":{"type":["string","null"],"description":"Madrid designation date for designation legs. Null for non-Madrid marks.","example":"2024-06-01"},"filing_date":{"type":["string","null"],"example":"2024-03-15"},"registration_date":{"type":["string","null"],"example":"2025-01-20"},"expiry_date":{"type":["string","null"],"description":"The expiry date the office published; null when it published none (the rulebook value is `derived.expiry_date`).","example":"2035-01-20"},"renewal_due_date":{"type":["string","null"],"description":"The renewal due date the office published; null when it published none.","example":"2035-01-20"},"last_renewal_date":{"type":["string","null"],"description":"The date of the last renewal the office recorded; null when it published none.","example":"2025-01-20"},"publication_date":{"type":["string","null"],"description":"First publication date when available. On an international registration (filing_route madrid_ir), the earliest WIPO Gazette publication across its designations: a derived date, not the national journal date an office may run opposition from.","example":"2024-11-05"},"termination_date":{"type":["string","null"],"example":"2026-02-01"},"priority_date":{"type":["string","null"],"example":"2024-01-15"},"register":{"$ref":"#/components/schemas/TrademarkRegister"},"classifications":{"type":"array","items":{"type":"object","properties":{"nice_class":{"type":["integer","null"],"description":"The Nice class number; null when the office states the goods/services without a class.","example":9},"goods_services_text":{"type":["string","null"],"example":"Computer software for trademark intelligence"},"goods_services_text_truncated":{"type":"boolean","description":"True when goods_services_text was shortened in a summary/list row. Use include=full_goods_services or fetch detail for the full text. Always false on detail.","example":false},"scope":{"type":"string","enum":["as_filed"],"description":"Classification scope on IR family rows: as filed, NOT territory-effective. Absent on other rows.","example":"as_filed"}},"required":["nice_class","goods_services_text","goods_services_text_truncated"]}},"nice_classes":{"type":"array","items":{"type":"integer","minimum":1,"maximum":45},"description":"Compact Nice class numbers derived from classifications[].nice_class.","example":[9,42]},"design_codes":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkDesignCode"}},"owners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"own_abc123"},"name":{"type":"string","description":"The name as filed on this record.","example":"Signa Technologies Inc."},"country_code":{"type":["string","null"],"example":"US"},"legal_form":{"type":["string","null"],"description":"The kind of legal person, normalised from the office's entity-type code; null when the office states none.","example":"corporation"},"entity_id":{"type":["string","null"],"description":"The entity linker's relationship: the resolved entity this owner belongs to. Null when the owner is not linked to an entity.","example":"ent_abc123"},"companies":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["sec","gleif"],"example":"sec"},"ticker":{"type":["string","null"],"example":"AAPL"},"exchange":{"type":["string","null"],"example":"NASDAQ"},"lei":{"type":["string","null"],"example":"7LTWFZYICNSX8D621K86"},"entity_status":{"type":"string","enum":["active","inactive","delisted"],"example":"active"}},"required":["source","ticker","exchange","lei","entity_status"]},"description":"Public company records linked to this owner. Absent when none."}},"required":["id","name","country_code","legal_form","entity_id"]},"description":"Current owners. Suppressed owners are never listed."},"has_media":{"type":"boolean"},"primary_image_url":{"type":["string","null"],"description":"Media-proxy URL for the primary mark image: the office-flagged image, else the first image. Always an image file, never a document, audio or video file. Null when the mark has no image.","example":"https://api.signa.so/v1/trademarks/tm_abc/media/01234567-89ab-cdef-0123-456789abcdef"},"derived":{"$ref":"#/components/schemas/DerivedBlock"},"updated_at":{"type":"string","example":"2026-03-18T04:00:00Z"},"coverage":{"allOf":[{"$ref":"#/components/schemas/GroupedCoverage"},{"description":"IR family rows only: per-territory coverage."}]},"source_records":{"type":"array","items":{"$ref":"#/components/schemas/SourceRecordRef"},"description":"IR family rows only: WIPO/national reconciliation alternates (§12.1)."},"owners_mixed":{"type":"boolean","description":"IR family rows only: true when the legs' current owners resolve to more than one holder."},"territory_matches":{"type":"array","items":{"$ref":"#/components/schemas/TerritoryMatch"},"description":"Search responses only, when a jurisdictions filter is active under the default protection mode: why this hit satisfied it."},"relevance_score":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Search responses only: how well the hit matches q (0–100), for ordering only, not a likelihood of confusion. Present on every hit when q is present, whatever the sort (under a sort the length factor does not apply). Null for rows matched only by a trademark number, for mark_text-only requests, and on metadata-only listings.","example":87},"match":{"$ref":"#/components/schemas/TrademarkMatch"},"highlights":{"type":["object","null"],"additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Search responses only: highlight fragments keyed by field name. Null when none were returned.","example":{"mark_text":["<em>SIGNA</em>"]}}},"required":["id","object","grain","mark_text","mark_feature_type","mark_legal_category","right_kind","status","office_code","jurisdiction_code","scope_kind","filing_route","origin_office_code","office_record_id","office_url","application_number","registration_number","ir_number","designation_date","filing_date","registration_date","expiry_date","renewal_due_date","last_renewal_date","publication_date","termination_date","priority_date","register","classifications","nice_classes","design_codes","owners","has_media","primary_image_url","derived","updated_at"],"description":"Shape-identical to a /v1/trademarks summary row, minus relevance_score."},"ScreeningHit":{"type":"object","properties":{"object":{"type":"string","enum":["screening_hit"]},"risk_level":{"type":"string","enum":["high","medium","low"],"description":"Coarse risk band — never a number."},"reason_codes":{"type":"array","items":{"type":"string"},"example":["exact_mark","same_nice_class","live_status"]},"mark_match":{"type":"object","properties":{"level":{"type":"string","enum":["identical","strong","weak"],"example":"identical"},"admitted_match_levels":{"type":"array","items":{"type":"string"},"description":"Which clause tiers passed the sensitivity threshold for this hit."}},"required":["level","admitted_match_levels"]},"goods_services_match":{"type":"object","properties":{"level":{"type":"string","enum":["same_class","related_class","unrelated"],"example":"same_class"},"matched_nice_classes":{"type":"array","items":{"type":"integer"},"example":[30]}},"required":["level","matched_nice_classes"]},"jurisdiction_match":{"type":"object","properties":{"requested":{"type":"array","items":{"type":"string"},"example":["US","EU"]},"matched":{"type":"array","items":{"type":"string"},"example":["US"]}},"required":["requested","matched"]},"litigation_risk":{"type":"object","properties":{"level":{"type":"string","enum":["low","medium","high","unknown"],"description":"Owner-level adversary risk — DISTINCT from risk_level (the legal-conflict band). \"unknown\" = the signals are not available on this result grain (not yet enriched), NOT a determined-low."},"owner_publicly_traded":{"type":["boolean","null"],"description":"True/false when determinable (a senior owner is a publicly-traded SEC-tickered company). null = data not available on this result grain."},"owner_ticker":{"type":["string","null"],"example":"AAPL"},"prior_proceedings":{"type":["integer","null"],"description":"TTAB oppositions/cancellations involving this mark. null until enriched."},"owner_portfolio_size":{"type":["integer","null"],"description":"How many marks the owner holds. null until enriched."}},"required":["level","owner_publicly_traded","owner_ticker","prior_proceedings","owner_portfolio_size"],"description":"How formidable the senior owner is to fight — a separate axis from risk_level. Not legal advice."},"band_source":{"type":"string","enum":["v1_table","v3_scorer"],"description":"Origin of the served band for this hit: \"v1_table\" when the v1 band table is active (default), or \"v3_scorer\" when the v3 calibrated-scorer strategy is active. Informational."},"model_assessment":{"type":"object","properties":{"band":{"type":"string","enum":["high","medium","borderline","low"]},"confidence":{"type":"string","enum":["high","medium","low"]},"band_source":{"type":"string","enum":["v1_table","v3_scorer"]}},"required":["band","confidence","band_source"],"description":"Additive v3 scorer read of this hit. Qualitative confidence tiers only, never a raw probability. Informational; never the served band."},"factor_ledger":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningFactorEntry"},"description":"DuPont-mapped factor ledger with raw observables (top-K evidence, payload-budgeted). Informational; not legal advice."},"trademark":{"$ref":"#/components/schemas/TrademarkSummaryV1"}},"required":["object","risk_level","reason_codes","mark_match","goods_services_match","jurisdiction_match","litigation_risk","trademark"]},"ScreeningHitV3":{"allOf":[{"$ref":"#/components/schemas/ScreeningHit"},{"type":"object","properties":{"band_source":{"type":"string","enum":["v1_table","v3_scorer"]},"model_assessment":{"type":"object","properties":{"band":{"type":"string","enum":["high","medium","borderline","low"]},"confidence":{"type":"string","enum":["high","medium","low"]},"band_source":{"type":"string","enum":["v1_table","v3_scorer"]}},"required":["band","confidence","band_source"]},"conflict_band":{"type":"string","enum":["high","medium","borderline","low"]},"factors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"contribution":{"type":"string","enum":["supports","weakens"]},"weight":{"type":"string","enum":["high","medium","low"]}},"required":["code","contribution","weight"]}}}}]},"ScreeningResponseV3":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"screening":{"$ref":"#/components/schemas/ScreeningMetaV3"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningHitV3"}},"request_id":{"type":"string"}},"required":["object","screening","data"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"not_found"},"title":{"type":"string","example":"Resource not found"},"status":{"type":"integer","example":404},"detail":{"type":"string","example":"Trademark tm_xxx does not exist."},"instance":{"type":"string","example":"/v1/trademarks/tm_xxx"},"suggestion":{"type":"string","example":"Check the trademark ID. Use GET /v1/trademarks to search for marks by text."},"retryable":{"type":"boolean","example":false},"retry_after":{"type":["integer","null"],"example":null},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","example":"limit"},"code":{"type":"string","description":"Stable machine-readable code (out_of_range, invalid_format, missing, invalid_value, too_long, too_short, ...).","example":"out_of_range"},"message":{"type":"string","example":"limit must be at most 100"}},"required":["field","code","message"]},"description":"Per-field validation issues. Present on every `validation_error`: one entry per failed field, or one entry with field `(request)` when the error concerns the request as a whole. Omitted on other error types."}},"required":["type","title","status","detail","retryable","retry_after"]},"request_id":{"type":"string","example":"req_abc123"}},"required":["error","request_id"]},"OfficeVoteResource":{"type":"object","properties":{"object":{"type":"string","enum":["office_vote"]},"office_code":{"type":"string","description":"Canonical WIPO ST.3 office code (uppercase), e.g. BR, MX, BX.","example":"BR"},"office_status":{"type":"string","enum":["live","roadmap","not_covered"],"description":"Current coverage of the voted office: `live` (now on Signa — your ask landed), `roadmap` (modeled, connector not shipping yet), `not_covered` (not modeled yet)."},"created_at":{"type":"string","description":"When this org first voted for the office."}},"required":["object","office_code","office_status","created_at"]},"OfficeVoteList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/OfficeVoteResource"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"OfficeVoteDeleted":{"type":"object","properties":{"object":{"type":"string","enum":["office_vote"]},"office_code":{"type":"string"},"deleted":{"type":"boolean","enum":[true]},"request_id":{"type":"string"}},"required":["object","office_code","deleted","request_id"]},"Classification":{"type":"object","properties":{"class_number":{"type":"integer","example":9},"object":{"type":"string","enum":["classification"]},"title":{"type":"string","example":"Electrical and scientific apparatus"},"description":{"type":["string","null"]},"category":{"type":["string","null"]}},"required":["class_number","object","title","description","category"]},"ClassificationListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Classification"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"GoodsServicesTerm":{"type":"object","properties":{"term":{"type":"string","example":"Computer software for data processing"},"term_key":{"type":"string","example":"computer-software-for-data-processing"},"class_number":{"type":"integer","example":9},"taxonomy_path":{"type":["string","null"],"example":"Software > Data Processing"},"is_harmonised":{"type":"boolean","example":true},"accepted_offices":{"type":"array","items":{"type":"string"},"description":"Offices whose goods & services catalogs accept this term, as identified by the upstream sources (TMclass/HDB, USPTO ID Manual). This is a catalog-acceptance vocabulary passed through verbatim — NOT the ST.3 `office_code` vocabulary used elsewhere in the API.","example":["USPTO","EUIPO","UKIPO","CIPO"]},"source":{"type":"string","example":"tmclass"},"language":{"type":"string","example":"en"}},"required":["term","term_key","class_number","taxonomy_path","is_harmonised","accepted_offices","source","language"]},"GoodsServicesTermListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesTerm"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"ClassificationDetail":{"allOf":[{"$ref":"#/components/schemas/Classification"},{"type":"object","properties":{"terms":{"type":"array","items":{"type":"string"}}},"required":["terms"]}]},"ClassificationDetailResponse":{"allOf":[{"$ref":"#/components/schemas/ClassificationDetail"},{"type":"object","properties":{"request_id":{"type":"string"}}}]},"ClassificationSuggestionLite":{"type":"object","properties":{"class_number":{"type":"integer","example":25},"title":{"type":"string","example":"Clothing, footwear, headwear"},"confidence":{"type":"string","enum":["high","medium","low"],"example":"high"},"rank":{"type":"integer","example":1},"recommendation_type":{"type":"string","enum":["core","conditional","adjacent"],"example":"core"},"conditional_on":{"type":["string","null"],"description":"Populated when `recommendation_type: \"conditional\"` — human-readable condition under which this class applies.","example":null},"rationale":{"type":"string","example":"Sneakers are athletic footwear, squarely in class 25."}},"required":["class_number","title","confidence","rank","recommendation_type","conditional_on","rationale"]},"ClassificationSuggestionResult":{"type":"object","properties":{"object":{"type":"string","enum":["classification_suggestion"]},"query":{"type":"string","example":"e-commerce company selling sneakers"},"classifier_version":{"type":"string","description":"Version tag of the prompt + reference data used to produce this response. Bumped on material changes.","example":"classify-v1.0"},"classes":{"type":"array","items":{"$ref":"#/components/schemas/ClassificationSuggestionLite"}},"ambiguous":{"type":"boolean","example":false},"clarification_question":{"type":["string","null"],"description":"Populated when `ambiguous: true` and a single disambiguating question fits.","example":null}},"required":["object","query","classifier_version","classes","ambiguous","clarification_question"]},"ClassificationSuggestionResponse":{"allOf":[{"$ref":"#/components/schemas/ClassificationSuggestionResult"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"AcceptedTerm":{"type":"object","properties":{"term":{"type":"string","example":"athletic footwear"},"source":{"type":"string","description":"Upstream catalog that contributed the term (e.g. `tmclass_hdb`, `uspto_idm`).","example":"tmclass_hdb"},"accepted_offices":{"type":"array","items":{"type":"string"},"description":"Offices whose goods & services catalogs accept this term, as identified by the upstream sources — a catalog-acceptance vocabulary passed through verbatim, NOT the ST.3 `office_code` vocabulary.","example":["USPTO","EUIPO","WIPO"]},"is_harmonised":{"type":"boolean","example":true}},"required":["term","source","accepted_offices","is_harmonised"]},"GoodsServicesSuggestionClass":{"type":"object","properties":{"class_number":{"type":"integer","example":25},"title":{"type":"string","example":"Clothing, footwear, headwear"},"confidence":{"type":"string","enum":["high","medium","low"],"example":"high"},"rank":{"type":"integer","example":1},"recommendation_type":{"type":"string","enum":["core","conditional","adjacent"],"example":"core"},"conditional_on":{"type":["string","null"],"description":"Populated when `recommendation_type: \"conditional\"` — human-readable condition under which this class applies.","example":null},"rationale":{"type":"string","example":"Sneakers are athletic footwear, squarely in class 25."},"accepted_terms":{"type":"array","items":{"$ref":"#/components/schemas/AcceptedTerm"}}},"required":["class_number","title","confidence","rank","recommendation_type","conditional_on","rationale","accepted_terms"]},"GoodsServicesSuggestionResult":{"type":"object","properties":{"object":{"type":"string","enum":["goods_services_suggestion"]},"query":{"type":"string","example":"e-commerce company selling sneakers"},"classifier_version":{"type":"string","description":"Version tag of the prompt + reference data used to produce this response. Bumped on material changes.","example":"classify-v1.0"},"classes":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesSuggestionClass"}},"ambiguous":{"type":"boolean","example":false},"clarification_question":{"type":["string","null"],"description":"Populated when `ambiguous: true` and a single disambiguating question fits.","example":null}},"required":["object","query","classifier_version","classes","ambiguous","clarification_question"]},"GoodsServicesSuggestionResponse":{"allOf":[{"$ref":"#/components/schemas/GoodsServicesSuggestionResult"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"ValidationItemStatus":{"type":"string","enum":["listed","not_listed","class_mismatch","ambiguous_class"],"description":"How the wording stands against the pre-approved catalogs: `listed` (this wording is in a catalog for the resolved class, exactly or after punctuation normalization — see `match.type`), `not_listed` (we cannot show it in any catalog we hold — an ABSENCE OF EVIDENCE, not a refusal), `class_mismatch` (the wording is catalogued, but in a different class — see `class_matches`), `ambiguous_class` (no class was supplied and the wording is catalogued in more than one — see `class_matches`).","example":"listed"},"GoodsServicesCatalogMatch":{"type":"object","properties":{"class_number":{"type":"integer","example":30},"term":{"type":"string","example":"Coffee"},"term_key":{"type":"string","example":"coffee"},"is_harmonised":{"type":"boolean","example":true},"listed_by":{"type":"array","items":{"type":"string"},"description":"ST.3 codes of the offices whose pre-approved catalogs LIST this wording. Not a statement that those offices accept, or would accept, any particular filing.","example":["US","EM","JP","KR","CN"]},"sources":{"type":"array","items":{"type":"string"},"description":"Catalog datasets carrying this row, sorted (`tmclass` = EUIPO Harmonised Database, `uspto_idm` = USPTO ID Manual).","example":["tmclass","uspto_idm"]},"taxonomy_path":{"type":["string","null"],"example":null}},"required":["class_number","term","term_key","is_harmonised","listed_by","sources","taxonomy_path"]},"GoodsServicesValidationMatch":{"allOf":[{"$ref":"#/components/schemas/GoodsServicesCatalogMatch"},{"type":"object","properties":{"type":{"type":"string","enum":["exact","normalized"],"description":"`exact` — the submitted wording normalizes to the stored term key verbatim. `normalized` — it matched after punctuation was stripped from both sides.","example":"exact"}},"required":["type"]}]},"OfficeVerdictStatus":{"type":"string","enum":["listed","not_listed","unsupported_office"],"description":"Per-office verdict: `listed` (this wording appears in that office's pre-approved catalog), `not_listed` (we cannot show it in that office's catalog — NOT a refusal, and not a prediction that the office would object), `unsupported_office` (we hold no catalog data for that office at all).","example":"listed"},"OfficeVerdictReason":{"type":["string","null"],"enum":["not_in_catalog","not_listed_at_office","class_mismatch","ambiguous_class","no_catalog_data",null],"description":"Null when `status` is `listed`.","example":null},"GoodsServicesOfficeVerdict":{"type":"object","properties":{"office_code":{"type":"string","description":"ST.3 office code, echoed from the request.","example":"US"},"status":{"$ref":"#/components/schemas/OfficeVerdictStatus"},"reason":{"$ref":"#/components/schemas/OfficeVerdictReason"}},"required":["office_code","status","reason"]},"WordingWarning":{"type":"object","properties":{"rule_id":{"type":"string","example":"us-open-ended-etc"},"office":{"type":"string","enum":["US","EM","GB"],"example":"US"},"severity":{"type":"string","enum":["objection","caution"],"example":"objection"},"reason":{"type":"string","example":"The office's guidelines treat “etc.” as indefinite wording."},"source":{"type":"object","properties":{"title":{"type":"string","example":"USPTO Trademark Manual of Examining Procedure — May 2026"},"section":{"type":"string","example":"TMEP §1402.03(a)"},"url":{"type":"string","example":"https://tmep.uspto.gov/"}},"required":["title","section","url"]}},"required":["rule_id","office","severity","reason","source"],"description":"`objection` means the cited guideline says the construction is indefinite or unclear; `caution` means acceptability depends on context or additional wording. A warning is guidance with a citation, not a prediction of refusal."},"GoodsServicesValidationSpan":{"type":"object","properties":{"start":{"type":"integer","minimum":0,"description":"Inclusive 0-based token index into the submitted item term.","example":2},"end":{"type":"integer","minimum":0,"description":"Exclusive 0-based token index into the submitted item term.","example":3}},"required":["start","end"],"description":"Half-open token span. Tokens are whitespace-separated words with leading/trailing punctuation removed."},"GoodsServicesValidationTemplateSlot":{"type":"object","properties":{"placeholder":{"type":"string","description":"The drafting instruction inside the template placeholder.","example":"indicate equipment or field of use"},"filled_with":{"type":["string","null"],"description":"Submitted wording between the surrounding fixed segments, or null when the slot is empty or cannot be assigned unambiguously.","example":"oil pipelines"}},"required":["placeholder","filled_with"]},"GoodsServicesValidationTemplate":{"type":"object","properties":{"pattern":{"type":"string","description":"The raw USPTO ID Manual template.","example":"Flowmeters for use in {indicate equipment or field of use}"},"slots":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesValidationTemplateSlot"}}},"required":["pattern","slots"],"description":"A pre-approved USPTO template whose fixed wording is contained in your input. Fill the placeholder to draft; a template is never a `listed` match."},"GoodsServicesValidationCandidate":{"type":"object","properties":{"term":{"type":"string","example":"T-shirts"},"term_key":{"type":"string","example":"t-shirts"},"class_number":{"type":"integer","example":25},"relation":{"type":"string","enum":["contained_in_input","similar","template"],"description":"`contained_in_input` — this catalogued wording appears verbatim as a whole-word run inside the submitted term. `similar` — lexically close, advisory only. `template` — the fixed wording of a USPTO drafting template appears in order; it is never a `listed` match.","example":"contained_in_input"},"score":{"type":"number","example":1},"score_metric":{"type":"string","enum":["strict_word_similarity","similarity"],"description":"Which pg_trgm metric produced `score`. The two are on different scales and are not comparable.","example":"strict_word_similarity"},"is_harmonised":{"type":"boolean","example":true},"listed_by":{"type":"array","items":{"type":"string"},"description":"ST.3 codes of the offices whose pre-approved catalogs LIST this wording. Not a statement that those offices accept, or would accept, any particular filing.","example":["US","EM","JP","KR","CN"]},"sources":{"type":"array","items":{"type":"string"},"description":"Catalog datasets carrying this row, sorted (`tmclass` = EUIPO Harmonised Database, `uspto_idm` = USPTO ID Manual).","example":["tmclass","uspto_idm"]},"span":{"anyOf":[{"$ref":"#/components/schemas/GoodsServicesValidationSpan"},{"type":"null"}],"description":"Token span into the submitted item term for `contained_in_input`, or from the first fixed segment through the last fixed segment for `template`; null for `similar` and templates with no fixed segments. Tokens are whitespace-separated words with leading/trailing punctuation removed."},"template":{"anyOf":[{"$ref":"#/components/schemas/GoodsServicesValidationTemplate"},{"type":"null"}],"description":"A pre-approved USPTO template whose fixed wording is contained in your input. Fill the placeholder to draft; a template is never a `listed` match. Null for non-template candidates."}},"required":["term","term_key","class_number","relation","score","score_metric","is_harmonised","listed_by","sources","span","template"]},"GoodsServicesValidationCoverage":{"type":"object","properties":{"tokens":{"type":"integer","minimum":0,"description":"Number of non-empty tokens in the item term. Tokens are whitespace-separated words with leading/trailing punctuation removed.","example":7},"covered_tokens":{"type":"integer","minimum":0,"description":"Number of covered item tokens. A verified exact/normalized catalog match covers every token; otherwise only verified word-run candidates actually returned count, plus connector-only glue between two covered spans. Connector glue is structural, not catalog-verified wording. Similar and template candidates never count.","example":5},"uncovered":{"type":"array","items":{"type":"string"},"description":"Maximal runs not covered by verified word-run candidates, using the original token text. Connector-only residue and connector words at a residue boundary are omitted. This is a coverage statement, never an acceptance verdict.","example":["sweatshirts"]}},"required":["tokens","covered_tokens","uncovered"],"description":"Coverage from a verified exact/normalized catalog match or from verified pre-approved word-run candidates actually returned. Tokens are whitespace-separated words with leading/trailing punctuation removed. Coverage is wording evidence, never an acceptance verdict."},"CandidateSearch":{"type":"string","enum":["complete","not_run","truncated","degraded"],"description":"`complete` means the search ran; an empty candidate list is then a real absence of nearby pre-approved wording. `not_run` means candidates were not applicable. `truncated` means we stopped before reaching this item's class/input chunk, not that nothing exists. `degraded` means a database error prevented a reliable search.","example":"complete"},"CandidateSearchReason":{"type":"string","enum":["no_class","not_needed","time_budget","database_error"],"description":"`no_class` — a classless miss cannot be searched safely. `not_needed` — the item was listed, class-mismatched, or class-ambiguous. `time_budget` — the item's candidate chunk was never issued. `database_error` — candidate retrieval failed.","example":"time_budget"},"GoodsServicesValidation":{"type":"object","properties":{"object":{"type":"string","enum":["goods_services_validation"]},"term":{"type":"string","description":"The submitted wording, echoed after trimming surrounding whitespace.","example":"coffee"},"class_number":{"type":["integer","null"],"example":30},"class_source":{"type":["string","null"],"enum":["provided","matched","inferred",null],"description":"`provided` — the class came from the request. `matched` — no class was supplied and the catalog resolved exactly one. `inferred` — the class was inferred from wording. Null when none applies.","example":"matched"},"class_inference":{"type":["object","null"],"properties":{"method":{"type":"string","enum":["keyword","llm"],"example":"keyword"},"confidence":{"type":"number","minimum":0,"maximum":1,"example":0.75}},"required":["method","confidence"],"description":"The class was inferred from the wording because none was supplied; treat it as a suggestion, and supply `class_number` to override. Null when `class_source` is not `inferred`."},"status":{"$ref":"#/components/schemas/ValidationItemStatus"},"match":{"anyOf":[{"$ref":"#/components/schemas/GoodsServicesValidationMatch"},{"type":"null"}],"description":"The catalog row this wording resolved to. Null unless `status` is `listed`."},"class_matches":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesCatalogMatch"},"description":"Catalog rows for this wording in classes OTHER than the resolved one — populated for `class_mismatch` and `ambiguous_class` so re-classing needs no second request. Always present; `[]` otherwise. Capped at 5."},"verdicts":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesOfficeVerdict"},"description":"One verdict per requested office, in request order."},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/WordingWarning"},"description":"Cited wording guidance for the requested offices. Always present; `[]` when no rule applies."},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesValidationCandidate"},"description":"Nearby pre-approved wording and USPTO template drafting aids from the same class, offered only when the wording is `not_listed` and a class is known. Advisory: adopting or filling a candidate is a drafting decision, not a guarantee of acceptance."},"coverage":{"anyOf":[{"$ref":"#/components/schemas/GoodsServicesValidationCoverage"},{"type":"null"}],"description":"Null when the candidate search did not run or did not complete for this item — we then have no evidence either way about which words are covered."},"candidate_search":{"$ref":"#/components/schemas/CandidateSearch"},"candidate_search_reason":{"anyOf":[{"$ref":"#/components/schemas/CandidateSearchReason"},{"type":"null"}],"description":"Null only when `candidate_search` is `complete`; otherwise explains why it did not complete.","example":null}},"required":["object","term","class_number","class_source","class_inference","status","match","class_matches","verdicts","warnings","candidates","coverage","candidate_search","candidate_search_reason"]},"GoodsServicesValidationCatalogFreshness":{"type":"object","properties":{"source":{"type":"string","description":"The catalog dataset: `uspto_idm` (USPTO ID Manual) or `tmclass` (EUIPO Harmonised Database).","example":"uspto_idm"},"as_of":{"type":["string","null"],"description":"UTC date (YYYY-MM-DD) this catalog was last refreshed from upstream — how fresh the evidence behind a `listed` verdict is, and how stale a `not_listed` may be. Null when we cannot determine it; a null is an unknown, never a claim that the catalog is current.","example":"2026-08-30"}},"required":["source","as_of"]},"GoodsServicesValidationSummaryOffice":{"type":"object","properties":{"office_code":{"type":"string","example":"US"},"supported":{"type":"boolean","description":"Whether we hold any pre-approved catalog data for this office.","example":true},"catalogs":{"type":"array","items":{"type":"string"},"description":"Catalog datasets backing this office (`uspto_idm`, `tmclass`); `[]` when `supported` is false.","example":["uspto_idm"]},"catalog_freshness":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesValidationCatalogFreshness"},"description":"One entry per id in `catalogs`, with the UTC date we last refreshed that dataset from its source. A null `as_of` means unknown, never current; it says nothing about the office's own publication schedule."},"listed_item_count":{"type":["integer","null"],"description":"How many submitted items this office's catalog lists. Null when `supported` is false — we hold no data, so we cannot know.","example":1}},"required":["office_code","supported","catalogs","catalog_freshness","listed_item_count"]},"GoodsServicesValidationSummaryClass":{"type":"object","properties":{"class_number":{"type":"integer","example":25},"item_count":{"type":"integer","description":"Submitted items resolved to this class.","example":2}},"required":["class_number","item_count"]},"GoodsServicesValidationSummaryCandidateSearch":{"type":"object","properties":{"complete_item_count":{"type":"integer","description":"Items whose same-class candidate search ran. An empty candidate list for these items is a real absence of nearby pre-approved wording.","example":1},"truncated_item_count":{"type":"integer","description":"Items whose class/input chunk was not issued before the time budget expired. This does not mean no nearby wording exists.","example":0},"degraded_item_count":{"type":"integer","description":"Items whose candidate search could not be completed because of a database error.","example":0}},"required":["complete_item_count","truncated_item_count","degraded_item_count"],"description":"Candidate-search outcomes across items. Items where candidate search was `not_run` are not counted."},"GoodsServicesValidationSummaryWarningCount":{"type":"object","properties":{"objection":{"type":"integer","minimum":0,"example":1},"caution":{"type":"integer","minimum":0,"example":0}},"required":["objection","caution"],"description":"Wording warnings across all items and requested offices, grouped by severity."},"GoodsServicesValidationSummary":{"type":"object","properties":{"language":{"type":"string","example":"en"},"matching_policy":{"type":"string","enum":["lexical-v1"],"description":"How wording was matched. `lexical-v1` is exact + punctuation-normalized lookup plus class-scoped word-containment; semantic matching would ship under a new policy tag."},"item_count":{"type":"integer","example":4},"unclassified_item_count":{"type":"integer","description":"Items with no class supplied and none matched or inferred.","example":0},"inferred_item_count":{"type":"integer","description":"Items whose class was inferred from their wording because none was supplied.","example":1},"offices":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesValidationSummaryOffice"}},"classes":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesValidationSummaryClass"}},"candidate_search":{"$ref":"#/components/schemas/GoodsServicesValidationSummaryCandidateSearch"},"warning_count":{"$ref":"#/components/schemas/GoodsServicesValidationSummaryWarningCount"},"fee_impact":{"type":"null","description":"Reserved for office fee data. Always null in v1."}},"required":["language","matching_policy","item_count","unclassified_item_count","inferred_item_count","offices","classes","candidate_search","warning_count","fee_impact"]},"GoodsServicesValidationListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesValidation"}},"has_more":{"type":"boolean","enum":[false]},"pagination":{"type":"object","properties":{"cursor":{"type":"null"}},"required":["cursor"]},"summary":{"$ref":"#/components/schemas/GoodsServicesValidationSummary"},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","summary","request_id"]},"GoodsServicesValidateItem":{"type":"object","properties":{"term":{"type":"string","minLength":1,"maxLength":1000,"example":"Clothing, namely, t-shirts, sweatshirts and hooded pullovers"},"class_number":{"type":"integer","minimum":1,"maximum":45,"description":"Nice class (1-45). Omit it to let the catalog resolve the class — a wording catalogued in exactly one class comes back `listed` with `class_source: \"matched\"`, one catalogued in several comes back `ambiguous_class`.","example":25}},"required":["term"],"additionalProperties":false},"GoodsServicesValidateRequest":{"type":"object","properties":{"offices":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"description":"Offices to report on, as ST.3 codes (legacy internal codes and the `EU` alias also resolve). At most 10 distinct offices are allowed after normalization. Duplicates and aliases of the same office collapse, and every code is echoed back as ST.3. An office we hold no catalog for is answered `unsupported_office` rather than rejected.","example":["US","EM","JP","GB"]},"language":{"type":"string","default":"en","description":"Catalog language. Only `en` is available today; other languages are not yet available.","enum":["en"],"example":"en"},"items":{"type":"array","items":{"$ref":"#/components/schemas/GoodsServicesValidateItem"},"minItems":1,"maxItems":100}},"required":["offices","items"],"additionalProperties":false},"OfficeDataCompleteness":{"type":["object","null"],"properties":{"images":{"type":["integer","null"],"minimum":0,"maximum":100,"example":64},"goods_services_text":{"type":["integer","null"],"minimum":0,"maximum":100,"example":76},"design_codes":{"type":["integer","null"],"minimum":0,"maximum":100,"example":15},"publication_date":{"type":["integer","null"],"minimum":0,"maximum":100,"example":81},"registration_number":{"type":["integer","null"],"minimum":0,"maximum":100,"example":94},"registration_date":{"type":["integer","null"],"minimum":0,"maximum":100,"example":92},"expiry_date":{"type":["integer","null"],"minimum":0,"maximum":100,"example":88},"priority_claims":{"type":["integer","null"],"minimum":0,"maximum":100,"example":7},"seniority_claims":{"type":["integer","null"],"minimum":0,"maximum":100,"example":3},"filing_basis":{"type":["integer","null"],"minimum":0,"maximum":100,"example":31},"first_use_date":{"type":["integer","null"],"minimum":0,"maximum":100,"example":24},"attorney_linkage":{"type":["integer","null"],"minimum":0,"maximum":100,"example":68},"owner_linkage":{"type":["integer","null"],"minimum":0,"maximum":100,"example":99},"status_effective_date":{"type":["integer","null"],"minimum":0,"maximum":100,"example":73}},"description":"Per-field completeness percentages for this office: the share of its records carrying each field, rounded to whole numbers. Dates count office-published values only (`expiry_date` = records whose office stated an expiry). Null until the stats worker has computed it."},"OfficeCapabilities":{"type":"object","properties":{"citations":{"type":"string","enum":["available","in_progress","not_available","not_applicable"],"description":"Office-action citation availability. `available` = served today; `in_progress` = pipeline being built; `not_available` = Signa serves no citations for this office. Either the office refuses on relative grounds and there is no pipeline yet, or its regime has not been classified. This state describes service availability and asserts nothing about the office's examination practice; `not_applicable` = this office performs no ex-officio relative-grounds examination, so citations will never exist for it.","example":"available"},"proceedings":{"type":"string","enum":["available","in_progress","not_available","not_applicable"],"description":"Proceedings (oppositions, cancellations, appeals) availability. `available` = Signa ingests and serves this office's proceedings; `in_progress` = pipeline being built; `not_available` = Signa serves no proceedings for this office. `GET /v1/proceedings` returns proceedings only from `available` offices, and a request scoped by `office_code` to a live office that is not `available` returns 422 `capability_not_available` without running a query or charging credits.","example":"available"}},"required":["citations","proceedings"],"description":"What this office can produce, independent of how much data we currently hold."},"Office":{"type":"object","properties":{"code":{"type":"string","example":"US"},"object":{"type":"string","enum":["office"]},"legacy_code":{"type":"string","example":"uspto"},"st3_code":{"type":["string","null"],"example":"US"},"acronym":{"type":["string","null"],"example":"USPTO"},"name":{"type":"string","example":"United States Patent and Trademark Office"},"name_en":{"type":["string","null"],"example":"United States Patent and Trademark Office"},"country_name":{"type":["string","null"],"example":"United States"},"jurisdiction_code":{"type":"string","example":"US"},"website_url":{"type":["string","null"]},"status":{"type":"string","enum":["live","paused"],"example":"live"},"update_cadence":{"type":["string","null"],"enum":["daily","weekly","monthly","on_demand",null],"example":"daily"},"total_marks":{"type":"integer","example":9200000},"last_synced_at":{"type":["string","null"],"example":"2026-03-18T04:00:00Z"},"data_completeness":{"$ref":"#/components/schemas/OfficeDataCompleteness"},"data_completeness_computed_at":{"type":["string","null"],"description":"Timestamp of the stats run that computed `data_completeness`, or null when it is not yet available.","example":"2026-03-18T05:00:00Z"},"capabilities":{"$ref":"#/components/schemas/OfficeCapabilities"}},"required":["code","object","legacy_code","st3_code","acronym","name","name_en","country_name","jurisdiction_code","website_url","status","update_cadence","total_marks","last_synced_at","data_completeness","data_completeness_computed_at","capabilities"]},"OfficeListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Office"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"OfficeDetail":{"type":"object","properties":{"code":{"type":"string","example":"US"},"object":{"type":"string","enum":["office"]},"legacy_code":{"type":"string","example":"uspto"},"st3_code":{"type":["string","null"],"example":"US"},"acronym":{"type":["string","null"],"example":"USPTO"},"name":{"type":"string","example":"United States Patent and Trademark Office"},"name_en":{"type":["string","null"],"example":"United States Patent and Trademark Office"},"country_name":{"type":["string","null"],"example":"United States"},"jurisdiction_code":{"type":"string","example":"US"},"website_url":{"type":["string","null"]},"status":{"type":"string","enum":["live","paused"],"example":"live"},"update_cadence":{"type":["string","null"],"enum":["daily","weekly","monthly","on_demand",null],"example":"daily"},"total_marks":{"type":"integer","example":9200000},"last_synced_at":{"type":["string","null"],"example":"2026-03-18T04:00:00Z"},"data_completeness":{"$ref":"#/components/schemas/OfficeDataCompleteness"},"data_completeness_computed_at":{"type":["string","null"],"description":"Timestamp of the stats run that computed `data_completeness`, or null when it is not yet available.","example":"2026-03-18T05:00:00Z"},"capabilities":{"$ref":"#/components/schemas/OfficeCapabilities"}},"required":["code","object","legacy_code","st3_code","acronym","name","name_en","country_name","jurisdiction_code","website_url","status","update_cadence","total_marks","last_synced_at","data_completeness","data_completeness_computed_at","capabilities"]},"OfficeDetailResponse":{"allOf":[{"$ref":"#/components/schemas/OfficeDetail"},{"type":"object","properties":{"request_id":{"type":"string"}}}]},"Jurisdiction":{"type":"object","properties":{"code":{"type":"string","example":"US"},"object":{"type":"string","enum":["jurisdiction"]},"name":{"type":"string","example":"United States"},"office_code":{"type":["string","null"],"example":"US"},"office_status":{"type":"string","enum":["live","roadmap","not_covered"],"description":"`live` = office connector is shipping data. `roadmap` = `office_code` references a planned office not yet on `/v1/offices`. `not_covered` = no office is associated with this jurisdiction.","example":"live"},"scope_type":{"type":"string","example":"national"},"madrid_member":{"type":"boolean"}},"required":["code","object","name","office_code","office_status","scope_type","madrid_member"]},"JurisdictionListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Jurisdiction"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"JurisdictionDetail":{"allOf":[{"$ref":"#/components/schemas/Jurisdiction"},{"type":"object","properties":{"member_jurisdictions":{"type":["array","null"],"items":{"type":"string"}},"wipo_contracting_party_code":{"type":["string","null"]}},"required":["member_jurisdictions","wipo_contracting_party_code"]}]},"JurisdictionDetailResponse":{"allOf":[{"$ref":"#/components/schemas/JurisdictionDetail"},{"type":"object","properties":{"request_id":{"type":"string"}}}]},"RuleSource":{"type":"object","properties":{"citation":{"type":"string"},"url":{"type":"string"}},"required":["citation","url"]},"DeadlineRule":{"type":"object","properties":{"object":{"type":"string","enum":["deadline_rule"]},"rule_id":{"type":"string","description":"Stable, permanent, opaque slug for this rule. Never renamed; do not parse it.","example":"us_declaration_of_use_s8"},"effective_from":{"type":["string","null"],"description":"Earliest date from which this rule’s modelled content is authoritative, or null when no boundary is established.","example":null},"last_verified":{"type":"string","description":"Date the parent jurisdiction config was last verified against its sources.","example":"2026-03-10"},"weekend_holiday_rule":{"type":"boolean","description":"Whether this rule’s dates roll to the next working day when they fall on a weekend/holiday. Per rule: the jurisdiction’s own opt-in for its national rules, and always true for a `madrid_only` renewal, whose period is the International Bureau’s and rolls under Madrid Regulations Rule 4(4) whatever the designated office does with its own dates.","example":true},"holiday_calendar":{"type":["string","null"],"description":"Internal identifier of the holiday calendar this rule’s dates roll against, or null when none applies. Per rule: the office’s wired calendar for its national rules, `wipo_geneva` for a `madrid_only` renewal (`mx_renewal_madrid`, `ca_renewal_madrid`).","example":"uspto_dc"},"grace_expiry_rolls_only":{"type":"boolean","description":"Whether the roll reported by weekend_holiday_rule is limited to the grace expiry. When true, the renewal due date is served exactly where the statutory arithmetic put it and is never moved to the next working day, because a late-filing surcharge in that jurisdiction keys on the calendar end of the registration period rather than on a deadline. True for AU, CA and NO; never true for a `madrid_only` renewal, whose period is the International Bureau’s.","example":false},"jurisdiction_code":{"type":"string","example":"US"},"name":{"type":"string","example":"Section 8 — Declaration of Use"},"type":{"type":"string","description":"Deadline type, the same vocabulary as `type` on computed rows. `post_registration_oa_response` is the USPTO response to a post-registration office action on a §8, §71 or §8+§9 filing.","example":"declaration_of_use"},"trigger":{"type":"string","description":"Record date the rule is anchored on. For a `restoration` rule this is the parent renewal rule’s trigger — restoration is anchored off the renewal chain. For `post_registration_oa_response` it is `post_registration_action`, the date of the office action.","example":"registration_date"},"due_year":{"type":"integer","description":"Year of the term the rule falls due in. For a `restoration` rule this identifies the RENEWAL CYCLE the restoration attaches to (the cycle it rescues), not a restoration due date — the restoration window itself is given by `window_months` + `starts_from`. 0 for `post_registration_oa_response`, which runs from an office action rather than a term year.","example":6},"earliest_filing_year":{"type":["integer","null"],"example":5},"earliest_filing_months_before":{"type":["integer","null"],"example":null},"grace_period_months":{"type":"integer","description":"Grace months after the due date. Always 0 for a `restoration` rule.","example":6},"consequence_if_missed":{"type":"string","example":"cancellation"},"recurring":{"type":"boolean","example":false},"recurring_interval_years":{"type":["integer","null"],"example":null},"optional":{"type":"boolean","example":false},"applies_to":{"type":["string","null"],"example":"domestic"},"renewal_period_years":{"type":"integer","example":10},"window_months":{"type":["integer","null"],"description":"Length of the restoration window in months, or of the response period on a `post_registration_oa_response` rule (six months from the action, or to the end of the pre-grace filing period when that is later: 37 CFR 2.163(b), 2.184(b)(1), 7.39(a)). Null on every other rule.","example":null},"starts_from":{"type":["string","null"],"enum":["grace_expiry","removal_date",null],"description":"Statutory anchor the restoration window runs from. Non-null only on `type: \"restoration\"` rules. It records the STATUTE, not the arithmetic Signa performs: computed restoration rows always anchor `window_opens` on the renewal’s grace expiry, because a removal date is not carried on a trademark record. That is exact where this is `grace_expiry` (IS), and a conservative approximation where it is `removal_date` (GB, SG): a client computing `removal_date` + `window_months` from its own removal data lands LATER than Signa by the removal lag.","example":null},"trigger_fallback":{"type":["string","null"],"description":"Anchor used when the rule’s own `trigger` field is absent from the record. Set only where the statute names a fallback: `in_renewal` anchors on `priority_date` (Trade Marks Act 1999 s. 154(2) registers a convention application as of the convention date) and falls back to `filing_date` for the far larger non-convention cohort (s. 23(1)). Null for every other rule, where a missing trigger means no deadline is emitted at all.","example":null},"window_opens_after_anniversary":{"type":"boolean","description":"Whether the filing window opens AFTER the anniversary rather than before it. True only for `mx_declaration_of_use_3yr`, whose window opens the day after the third anniversary and stays open `window_duration_months`.","example":false},"window_duration_months":{"type":["integer","null"],"description":"How long the filing window stays open, in months. Non-null only alongside `window_opens_after_anniversary`.","example":null},"window_change_date":{"type":["string","null"],"description":"Date an era pivot INSIDE the rule changed the FILING WINDOW (not the due date or the grace expiry). Half-open like the opposition catalog’s field of the same name. Per cycle: a window the legacy spec would already have opened on this date keeps the legacy shape; every other cycle takes the current shape, floored at this date. Today: `ph_declaration_of_use_renewal` (2023 Regulations Rule 206, in force 2023-02-14).","example":null},"window_before":{"type":["object","null"],"properties":{"earliest_filing_year":{"type":["integer","null"]},"earliest_filing_months_before":{"type":["integer","null"]},"window_opens_after_anniversary":{"type":"boolean"}},"required":["earliest_filing_year","earliest_filing_months_before","window_opens_after_anniversary"],"description":"The filing-window shape that applied before `window_change_date`. Set together with it and null whenever it is null. Exactly one of the two length fields is non-null."},"grace_starts_day_after_due":{"type":"boolean","description":"Whether the grace period is counted from the day AFTER the unrolled due date rather than from the due date itself. True for `fr_renewal`; a client counting from the due date lands one day early on every French grace expiry.","example":false},"extension_months":{"type":["integer","null"],"description":"Further extension available on request before the deadline, in months. Advisory: never included in the computed due date. Today: the PH 3-year DAU rules.","example":null},"applicable_from_date":{"type":["string","null"],"description":"The rule applies only to marks registered on or after this date. Null when it has always applied.","example":null},"ignore_config_trigger_change":{"type":"boolean","description":"Whether this rule resolves its trigger directly, ignoring the jurisdiction-level `trigger_change_date` transition. Published so a client applying that transition to every rule of a jurisdiction knows which one to skip (today: the MX 3-year declaration of use, which always anchors on the grant date).","example":false},"trigger_change_date":{"type":["string","null"],"description":"Date the JURISDICTION changed which record date anchors the term. Marks selected by `trigger_change_comparison_field` before this date use `trigger_before`; the rest use the rule’s `trigger`. Today: SE, NO, DK, FI, IS, MX.","example":null},"trigger_change_comparison_field":{"type":["string","null"],"enum":["filing_date","registration_date","grant_date",null],"description":"Which date of the mark selects the pre/post cohort for `trigger_change_date`. Null whenever that field is null.","example":null},"trigger_before":{"type":["string","null"],"description":"The anchor that applied before `trigger_change_date`. Null whenever that field is null.","example":null},"trigger_before_proves_cohort":{"type":"boolean","description":"Whether a mark WITHOUT the `trigger_change_comparison_field` date, whose `trigger_before` date falls before `trigger_change_date`, is in the old cohort and anchored on `trigger_before`. Without it such a mark resolves the rule’s `trigger`. True where the transitional law reaches marks registered before the change: SE, NO, FI, IS. False everywhere else; for DK and MX the comparison field is itself the old anchor.","example":false},"renewal_window_months_before":{"type":"integer","description":"How many months before the due date the renewal request window opens. Previously only `renewal_period_years` was published, which made the window’s opening unreproducible from the catalog. Applies to the national route. For Madrid designations of the same rule the window opens six months before the due date (Common Regulations Rule 30(1)(b)), regardless of this value.","example":6},"term_counts_trigger_day":{"type":"boolean","description":"Whether the statutory term COUNTS the trigger day itself, so it ends the day BEFORE the anniversary. True for CN on the national route only (商标法实施条例 第十二条第二款): a mark registered 2016-03-07 expires 2026-03-06. A client using the plain anniversary is one day late on every Chinese renewal. National route only; Madrid designations of the same rule ignore it.","example":false},"end_of_month_rule":{"type":"boolean","description":"Whether expiry falls at the END OF THE MONTH rather than on the exact anniversary, for the cohort before `end_of_month_cutoff`. True for DE (pre-2019 marks). National route only; Madrid designations of the same rule ignore it.","example":false},"end_of_month_cutoff":{"type":["string","null"],"description":"Cutoff selecting the `end_of_month_rule` cohort. A mark whose `end_of_month_comparison_field` date is before it keeps the month-end expiry for EVERY cycle, not just the first.","example":null},"end_of_month_comparison_field":{"type":["string","null"],"enum":["filing_date","registration_date",null],"description":"Which date of the mark selects the `end_of_month_rule` cohort. Null whenever `end_of_month_cutoff` is null.","example":null},"renewal_window_end_of_month_until":{"type":["string","null"],"description":"Per-cycle transitional anchoring of the renewal REQUEST WINDOW: a cycle whose exact anniversary falls strictly before this date has its `window_opens` and `due_date` derived from the end of the anniversary month. The grace expiry is deliberately NOT moved: it stays on the exact anniversary. Distinct from `end_of_month_cutoff`, which is keyed on the mark and moves the expiry itself. Today: TR (KHK 556 m. 41/3 vs m. 41/5). National route only; Madrid designations of the same rule ignore it.","example":null},"first_renewal_after_cutoff_opens_at_period_start":{"type":["string","null"],"description":"Statutory coming-into-force day on which the FIRST renewal of an already-registered mark opens at the cycle’s PERIOD START (day of registration or of last renewal) instead of `due_date` minus `renewal_window_months_before`. Applies only to the one cycle that straddles the day. Today: CA (Trademarks Regulations SOR/2018-227 s. 159, in force 2019-06-17); the served window can only open EARLIER than the six-month default, never later. National route only; Madrid designations of the same rule ignore it.","example":null},"month_end_overflow":{"type":"string","enum":["last_day","first_business_day_of_following_month"],"description":"What a month- or year-counted period does when its end day does not exist in the target month (31 August + 6 months; 29 February + 1 year). `last_day` clamps to that month’s last day, the default and the behaviour of every office but Mexico. `first_business_day_of_following_month` runs the period into the next calendar month (MX, Reglamento LFPPI art. 7, párrafo segundo). Applied to the due date and the grace expiry, never to `window_opens`. Like `holiday_calendar` and `grace_expiry_rolls_only`, this is resolved PER RULE: art. 7 is the designated office’s own convention, so a rule whose period belongs to the International Bureau reports `last_day` whatever its jurisdiction configures (Madrid Regulations Rule 4(1) and (2) clamp such a period to the month’s last day).","example":"last_day"},"term_schedule":{"type":["object","null"],"properties":{"initial_term_years":{"type":"integer"},"legacy_term_years":{"type":"integer"},"modern_term_years":{"type":"integer"},"cutoff":{"type":"string"}},"required":["initial_term_years","legacy_term_years","modern_term_years","cutoff"],"description":"Statutory term ladder for a jurisdiction whose PERIOD LENGTH changed on a cutoff: the first term runs `initial_term_years`, and each later period runs `legacy_term_years` while its period START is before `cutoff`, `modern_term_years` from then on. When present the renewal ladder is walked period-to-period instead of by a fixed interval, so `renewal_period_years` alone does not reproduce the dates. Today: CA (15 → 10 on 2019-06-17) and IN (7 → 10 on 2003-09-15). National route only; Madrid designations of the same rule ignore it."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/RuleSource"}}},"required":["object","rule_id","effective_from","last_verified","weekend_holiday_rule","holiday_calendar","grace_expiry_rolls_only","jurisdiction_code","name","type","trigger","due_year","earliest_filing_year","earliest_filing_months_before","grace_period_months","consequence_if_missed","recurring","recurring_interval_years","optional","applies_to","renewal_period_years","window_months","starts_from","trigger_fallback","window_opens_after_anniversary","window_duration_months","window_change_date","window_before","grace_starts_day_after_due","extension_months","applicable_from_date","ignore_config_trigger_change","trigger_change_date","trigger_change_comparison_field","trigger_before","trigger_before_proves_cohort","renewal_window_months_before","term_counts_trigger_day","end_of_month_rule","end_of_month_cutoff","end_of_month_comparison_field","renewal_window_end_of_month_until","first_renewal_after_cutoff_opens_at_period_start","month_end_overflow","term_schedule","sources"]},"DeadlineRuleListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DeadlineRule"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"OppositionExtension":{"type":"object","properties":{"days":{"type":["integer","null"]},"months":{"type":["integer","null"]},"as_of_right":{"type":"boolean"},"notes":{"type":"string"}},"required":["days","months","as_of_right","notes"]},"OppositionRule":{"type":"object","properties":{"object":{"type":"string","enum":["opposition_rule"]},"rule_id":{"type":"string","example":"eu_opposition_madrid"},"effective_from":{"type":["string","null"],"example":null},"last_verified":{"type":"string","example":"2026-05-06"},"jurisdiction_code":{"type":"string","example":"EU"},"office_code":{"type":"string","example":"EM"},"filing_route":{"type":"string","enum":["domestic","madrid_designation"],"example":"madrid_designation"},"trigger_event":{"type":"string","enum":["application_publication","registration_publication","international_designation_publication"],"example":"international_designation_publication"},"window_months":{"type":["integer","null"],"example":3},"window_days":{"type":["integer","null"],"example":null},"window_starts_offset_months":{"type":["integer","null"],"example":1},"window_starts_on":{"type":"string","enum":["date_of_publication","day_after","first_of_following_month"],"description":"Start convention for the CURRENT era. When `window_change_date` is non-null, publications strictly before it use `window_starts_on_before` instead.","example":"day_after"},"window_opens_on":{"type":["string","null"],"enum":["first_of_following_month",null],"description":"When non-null, the CURRENT era’s window does not OPEN until the first day of the month after the publication month, although its close is still counted per `window_starts_on` (from the publication). Null for every rule but `cn_opposition_madrid`, whose window for a WIPO Gazette date on or after 2027-01-01 is provisional on CNIPA’s draft transitional measures: it opens on the later of two readings (the 1st of the following month) and closes on the earlier (two months from the publication).","example":null},"window_ends_on":{"type":["string","null"],"enum":["corresponding_day_of_start","day_before_corresponding_day_of_start",null],"description":"How the close is counted for the CURRENT era when it opens on the first of the following month with a month-based window. Null for every other rule AND for a rule that only opens that way in its earlier era — see `window_ends_on_before`.","example":null},"window_change_date":{"type":["string","null"],"description":"Date the rule changed regime, half-open: a publication STRICTLY BEFORE it is governed by the `_before` fields, one on or after it by the current-era fields. Null when the rule has never changed. (One rule, `tr_opposition`, keys this comparison on the FILING date rather than the publication date under its transitional provision.)","example":null},"window_change_comparison_field":{"type":["string","null"],"enum":["publication_date","filing_date",null],"description":"Which date of the mark is compared against `window_change_date` to select the era. `publication_date` (the publication the window runs from) for every rule but one: `tr_opposition` compares the application’s FILING date, because SMK geçici m. 1/1 concludes an application filed before the SMK under the law in force on its filing date, so a mark filed under KHK 556 and published after the pivot keeps the older, longer window. Null exactly when `window_change_date` is null.","example":null},"window_starts_on_before":{"type":["string","null"],"enum":["date_of_publication","day_after","first_of_following_month",null],"description":"Start convention for publications before `window_change_date`, when the pivot changed the start. Null when the pivot changed only the length (or there is no pivot) — then the current `window_starts_on` governs both eras.","example":null},"window_months_before":{"type":["integer","null"],"description":"Window length in MONTHS for publications before `window_change_date`. Null when the pre-pivot length was counted in days (`window_days_before`), when the pivot changed only the start convention, or when there is no pivot.","example":null},"window_days_before":{"type":["integer","null"],"description":"Window length in DAYS for publications before `window_change_date`. Exactly one of `window_months_before` / `window_days_before` is non-null when the pivot changed the length; a pivot may switch units (KR went from 2 months to 30 days).","example":null},"window_ends_on_before":{"type":["string","null"],"enum":["corresponding_day_of_start","day_before_corresponding_day_of_start",null],"description":"How the close is counted for the pre-`window_change_date` era, when THAT era opens on the first of the following month with a month-based window. `bx_opposition` is the rule this exists for.","example":null},"month_end_overflow":{"type":"string","enum":["last_day","first_business_day_of_following_month"],"description":"What a month-counted close date does when the publication's day number does not exist in the target month. `last_day` clamps to that month's last day, which is the default and what every office except Mexico does. `first_business_day_of_following_month` runs the period into the next calendar month and ends it on that month's first business day (Mexico, Reglamento LFPPI art. 7, párrafo segundo). Never applies to a day-counted window.","example":"last_day"},"office_time_zone":{"type":"string","example":"Europe/Madrid"},"holiday_calendar":{"type":["string","null"],"example":"euipo_alicante"},"common_extension":{"anyOf":[{"$ref":"#/components/schemas/OppositionExtension"},{"type":"null"}]},"extension_change_date":{"type":["string","null"],"description":"Date the office changed its common-extension benchmark, exclusive upper bound of the `_before` era: a window whose served `window_closes` falls STRICTLY BEFORE it is governed by `common_extension_before`, every other window (and a window with no publication date) by `common_extension`. Advisory only: the pivot never moves the statutory close. Null when the benchmark has never changed. Today: `ca_opposition` (CIPO TMOB, 2023-12-01, 4 → 2 months) and `ph_opposition` (IPOPHL MC 2022-013, 2022-06-30, 3×30 days → 1×45 days).","example":null},"common_extension_before":{"anyOf":[{"$ref":"#/components/schemas/OppositionExtension"},{"type":"null"}],"description":"The common-extension benchmark that applied before `extension_change_date`. Set together with it, and null whenever it is null."},"applicable_from_date":{"type":["string","null"],"example":null},"sources":{"type":"array","items":{"$ref":"#/components/schemas/RuleSource"}}},"required":["object","rule_id","effective_from","last_verified","jurisdiction_code","office_code","filing_route","trigger_event","window_months","window_days","window_starts_offset_months","window_starts_on","window_opens_on","window_ends_on","window_change_date","window_change_comparison_field","window_starts_on_before","window_months_before","window_days_before","window_ends_on_before","month_end_overflow","office_time_zone","holiday_calendar","common_extension","extension_change_date","common_extension_before","applicable_from_date","sources"]},"OppositionRuleListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/OppositionRule"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"ProsecutionRuleSource":{"type":"object","properties":{"citation":{"type":"string","example":"37 CFR 2.62"},"url":{"type":"string","example":"https://www.ecfr.gov/current/title-37/section-2.62"},"section":{"type":"string","example":"37 CFR 2.62(a)(1)(ii)"},"quoted_text":{"type":"string","description":"Verbatim operative text, so the value is auditable without a re-fetch."},"snapshot_sha256":{"type":["string","null"],"description":"sha256 of the snapshotted source document in the evidence pack."},"authority_level":{"type":["string","null"],"enum":["statute","regulation","office_practice","office_notice",null],"description":"Where THIS source sits in the hierarchy, when it differs from the rule's governing level."},"last_checked":{"type":"string","example":"2026-08-31"}},"required":["citation","url","section","quoted_text","snapshot_sha256","authority_level","last_checked"]},"ProsecutionRule":{"type":"object","properties":{"object":{"type":"string","enum":["prosecution_rule"]},"rule_id":{"type":"string","description":"Stable, permanent id for this rule, equal to the `rule.rule_id` on a computed prosecution deadline from `POST /v1/deadlines/compute`. Era-versioned rules carry an `@<date>` or `@legacy` suffix (`uspto_domestic_oa_response@2022-12-03`); others have none (`uspto_domestic_sou`). Opaque: compare it for equality, do not parse it.","example":"uspto_domestic_oa_response@2022-12-03"},"jurisdiction_code":{"type":"string","example":"US"},"office_code":{"type":"string","example":"US"},"route":{"type":"string","enum":["direct_national","madrid_designation","any"],"description":"Filing route the rule applies to. `any` = the rule applies regardless of route (e.g. USPTO post-registration office actions).","example":"direct_national"},"deadline_type":{"type":"string","enum":["oa_response","suspension_inquiry_response","post_registration_oa_response","sou"],"example":"oa_response"},"applies_when":{"type":"string","description":"Human-readable statement of when this rule applies.","example":"Section 1/44 refusal Office actions issued on or after 3 December 2022."},"period":{"type":"object","properties":{"value":{"type":"integer","example":3},"unit":{"type":"string","enum":["month","day"],"example":"month"},"counting":{"type":"string","enum":["anniversary_day_short_month_fallback","day_after_anniversary_day_short_month_fallback","day_after_end_of_month_carry","calendar_days_from_day_after"],"description":"How the period is counted off the trigger date. `anniversary_day_short_month_fallback` is US practice (TMEP 310). Values containing `day_after` (`day_after_anniversary_day_short_month_fallback`, `day_after_end_of_month_carry`, `calendar_days_from_day_after`) start the clock the day after the triggering event, as in the EU (Art 67 EUTMDR 2018/625)."}},"required":["value","unit","counting"],"description":"The response period measured from the trigger date."},"roll_rule":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["next_business_day"]},"calendar":{"type":"string","example":"uspto_dc"},"authority":{"type":"string","example":"37 CFR 2.196; 35 USC 21(b)"}},"required":["kind","calendar","authority"],"description":"Weekend/holiday adjustment applied to the computed due date, or null where the office applies no roll."},"extensions":{"type":"array","items":{"type":"object","properties":{"ordinal":{"type":"integer","example":1},"length":{"type":"object","properties":{"value":{"type":"integer","example":3},"unit":{"type":"string","enum":["month","day"],"example":"month"}},"required":["value","unit"]},"fee":{"type":["object","null"],"properties":{"amount":{"type":"number","example":125},"currency":{"type":"string","example":"USD"},"per":{"type":"string","enum":["request","class","class_per_request"]},"authority":{"type":"string","example":"37 CFR 2.6(a)(28)(ii)"}},"required":["amount","currency","per","authority"]},"request_deadline":{"type":"string","enum":["on_or_before_current_deadline"]},"conditions":{"type":"array","items":{"type":"string"}},"discretionary":{"type":"boolean","description":"false = non-discretionary on a timely, fee-paid request."}},"required":["ordinal","length","fee","request_deadline","conditions","discretionary"]},"description":"The extension ladder. Empty = the deadline is never extendable."},"not_earlier_than":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["statutory_maintenance_window_end"]},"authority":{"type":"string","example":"37 CFR 2.163(b)"},"window":{"type":"string","enum":["section_8","section_71","section_9","any_pending"]}},"required":["kind","authority","window"],"description":"\"Whichever is later\" floor: the computed date is raised to this statutory window end when it falls later. Null for rules without a later-of limb."},"absolute_cap":{"type":["object","null"],"properties":{"value":{"type":"integer"},"unit":{"type":"string","enum":["month","day"]},"measured_from":{"type":"string","enum":["trigger_date"]},"authority":{"type":"string"}},"required":["value","unit","measured_from","authority"],"description":"Statutory ceiling on the extended deadline, measured from the trigger date."},"consequence":{"type":"string","enum":["abandonment","partial_abandonment","refusal","deemed_withdrawn","loss_of_right","none"],"description":"What happens when the deadline (and every extension) is missed."},"remedy":{"type":"object","properties":{"kind":{"type":"string","enum":["petition_to_revive","continuation_of_proceedings","restitutio_in_integrum","reinstatement","appeal","none"]},"window":{"type":["object","null"],"properties":{"value":{"type":"integer","example":3},"unit":{"type":"string","enum":["month","day"],"example":"month"}},"required":["value","unit"]},"starts_from":{"type":["string","null"],"enum":["abandonment_notice_issue_date","cancellation_or_expiration_notice_issue_date","actual_knowledge","due_date_expiry","removal_of_obstacle",null]},"fee":{"type":["object","null"],"properties":{"amount":{"type":"number","example":125},"currency":{"type":"string","example":"USD"},"per":{"type":"string","enum":["request","class","class_per_request"]},"authority":{"type":"string","example":"37 CFR 2.6(a)(28)(ii)"}},"required":["amount","currency","per","authority"]},"authority":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}},"required":["kind","window","starts_from","fee","authority","notes"],"description":"The relief available after the consequence has attached."},"authority_level":{"type":"string","enum":["statute","regulation","office_practice","office_notice"],"description":"The governing authority level for this rule's value as a whole. `office_practice` marks values that exist only in practice material (e.g. TMEP), not statute or regulation."},"effective_from":{"type":"string","description":"When this rule era began (ISO date).","example":"2022-12-03"},"effective_until":{"type":["string","null"],"description":"INCLUSIVE last day the era was in force, or null while still in force. A case date equal to this value selects THIS era.","example":null},"applicability_basis":{"type":"string","enum":["office_action_issue_date","notice_of_allowance_issue_date","time_limit_set_date","notification_date","application_filing_date","registration_date","proceeding_institution_date"],"description":"WHICH case date selects the era. Not the same as `effective_from`: the US 3-month OA period keys off the OA issue date; EUIPO objection regimes key off the date the time limit was set."},"last_verified":{"type":"string","example":"2026-08-30"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ProsecutionRuleSource"}}},"required":["object","rule_id","jurisdiction_code","office_code","route","deadline_type","applies_when","period","roll_rule","extensions","not_earlier_than","absolute_cap","consequence","remedy","authority_level","effective_from","effective_until","applicability_basis","last_verified","sources"]},"ProsecutionRuleListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProsecutionRule"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"OfficeCodeLabel":{"type":"object","properties":{"code":{"type":"string","description":"The office's verbatim code.","example":"800"},"label":{"type":["string","null"],"description":"The office's verbatim label; null when the office publishes none. Never rewritten.","example":"REGISTERED AND RENEWED"}},"required":["code","label"]},"EventTypeMapping":{"type":"object","properties":{"object":{"type":"string","enum":["event_type_mapping"]},"office_code":{"type":"string","example":"US"},"raw":{"$ref":"#/components/schemas/OfficeCodeLabel"},"event_type":{"type":"string","example":"assignment"},"event_scope":{"type":["string","null"]},"notes":{"type":["string","null"]}},"required":["object","office_code","raw","event_type","event_scope","notes"]},"EventTypeListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EventTypeMapping"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"StatusCode":{"type":"object","properties":{"object":{"type":"string","enum":["status_code"]},"office_code":{"type":"string","description":"WIPO ST.3 office code.","example":"EM"},"raw":{"$ref":"#/components/schemas/OfficeCodeLabel"},"primary":{"type":"string","enum":["pending","active","inactive","unknown"],"example":"active"},"stage":{"type":"string","enum":["filed","examining","pending_publication","published","opposition_period","pending_opposition","pending_cancellation","pending_issuance","registered","allowed","abandoned","withdrawn","surrendered","refused","cancelled","invalidated","expired","unknown"],"example":"registered"},"reason":{"type":["string","null"],"enum":["refused","withdrawn","abandoned","cancelled","invalidated","expired","surrendered","revoked","other",null],"example":null}},"required":["object","office_code","raw","primary","stage","reason"]},"StatusCodeListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/StatusCode"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"DesignCode":{"type":"object","properties":{"code":{"type":"string","example":"03.05"},"object":{"type":"string","enum":["design_code"]},"category":{"type":"string","example":"03"},"division":{"type":["string","null"],"example":"05"},"section":{"type":["string","null"]},"depth":{"type":"integer","example":2},"description":{"type":"string","example":"Bears"}},"required":["code","object","category","division","section","depth","description"]},"DesignCodeListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DesignCode"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"DesignCodeChild":{"type":"object","properties":{"code":{"type":"string","example":"03.01"},"description":{"type":"string","example":"Quadrupeds (in general)"},"depth":{"type":"integer","example":2}},"required":["code","description","depth"]},"DesignCodeDetail":{"allOf":[{"$ref":"#/components/schemas/DesignCode"},{"type":"object","properties":{"notes":{"type":["string","null"]},"children":{"type":"array","items":{"$ref":"#/components/schemas/DesignCodeChild"}}},"required":["notes","children"]}]},"DesignCodeDetailResponse":{"allOf":[{"$ref":"#/components/schemas/DesignCodeDetail"},{"type":"object","properties":{"request_id":{"type":"string"}}}]},"ImageSearchHit":{"type":"object","properties":{"object":{"type":"string","enum":["image_search_hit"]},"score":{"type":"number","description":"Fused (visual) score — version-scoped."},"band":{"type":"string","enum":["identical","strong","moderate","weak"]},"signals":{"type":"object","properties":{"visual":{"type":"object","properties":{"score":{"type":"number","description":"Raw cosine similarity (version-scoped)."},"band":{"type":"string","enum":["identical","strong","moderate","weak"]},"embedding_spec":{"type":"string","example":"visual/dinov2-vitb14-reg@1/cls+mean/224/pp@1"}},"required":["score","band","embedding_spec"]},"logo_text":{"type":["object","null"],"properties":{"query_text":{"type":"string"},"matched_clause":{"type":"string","enum":["exact","normalized","token_overlap"]}},"required":["query_text","matched_clause"]},"exact_dup":{"type":["object","null"],"properties":{"checksum_match":{"type":"boolean"},"phash_distance":{"type":["integer","null"]}},"required":["checksum_match","phash_distance"]},"vienna_overlap":{"type":["object","null"],"properties":{"codes":{"type":"array","items":{"type":"string"}}},"required":["codes"]}},"required":["visual","logo_text","exact_dup","vienna_overlap"],"description":"The §3.5 named signal channels — the explanation block."},"matched_image":{"type":"object","properties":{"image_id":{"type":"string"},"checksum":{"type":"string"},"office":{"type":"string"},"jurisdiction":{"type":"string"},"thumbnail_url":{"type":["string","null"],"description":"Proxy URL for the 256px WebP."}},"required":["image_id","checksum","office","jurisdiction","thumbnail_url"]},"thumbnail_url":{"type":["string","null"]},"trademark":{"$ref":"#/components/schemas/TrademarkSummaryV1"}},"required":["object","score","band","signals","matched_image","thumbnail_url","trademark"]},"ImageSearchMeta":{"type":"object","properties":{"search_id":{"type":"string"},"query_mode":{"type":"string","enum":["upload","image_url","media_id"]},"channels":{"type":"array","items":{"type":"string","enum":["visual","logo_text","exact_dup","vienna_overlap"]}},"embedding_spec":{"type":"string"},"retrieval_bundle":{"type":"string"},"index_version":{"type":"integer"},"execution_time_ms":{"type":"number"},"territory_match":{"type":"string","enum":["protection","direct"],"description":"The applied protection-scope mode: \"protection\" (default — a jurisdictions filter also surfaces regional logos, e.g. FR→EUTM) or \"direct\" (literal-leg only)."}},"required":["search_id","query_mode","channels","embedding_spec","retrieval_bundle","index_version","execution_time_ms","territory_match"],"description":"Image-search execution metadata."},"ImageSearchResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ImageSearchHit"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"search_meta":{"$ref":"#/components/schemas/ImageSearchMeta"},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","search_meta","request_id"]},"ImageSearchBody":{"type":"object","properties":{"image_url":{"type":"string","format":"uri","description":"https URL of the query image (SSRF-guarded)."},"media_id":{"type":"string","description":"Existing media id (med_…) — reuse its stored vector."},"filters":{"type":"object","properties":{"offices":{"type":"array","items":{"type":"string","minLength":1,"maxLength":32},"maxItems":50},"jurisdictions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":16},"maxItems":50},"statuses":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20},"include":{"type":"string","enum":["live","all"]},"nice_classes":{"type":"array","items":{"type":"integer","minimum":1,"maximum":45},"maxItems":45},"feature_types":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20},"vienna_codes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":24},"maxItems":50},"design_code_keys":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":50}},"description":"Efficient-filtered facets applied inside the knn query."},"territory_match":{"type":"string","enum":["protection","direct"],"description":"How filters.jurisdictions matches: protection (default) or direct (literal territory legs only)."},"crop":{"type":"object","properties":{"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1},"w":{"type":"number","exclusiveMinimum":0,"maximum":1},"h":{"type":"number","exclusiveMinimum":0,"maximum":1}},"required":["x","y","w","h"],"description":"Normalized crop box (fractions of width/height) applied before embedding."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"Bounded top-K page size (1-100, default 20). ANN results are not deep-pageable."},"channels":{"type":"array","items":{"type":"string","enum":["visual","logo_text","exact_dup","vienna_overlap"]},"minItems":1,"maxItems":4,"description":"Subset of §3.5 signal channels. Default: visual, logo_text, exact_dup."}}},"ImageSearchMultipart":{"type":"object","properties":{"image":{"type":"string","description":"The query image file (≤8MB, raster only — no SVG).","format":"binary"},"image_url":{"type":"string","description":"https URL of the query image (SSRF-guarded)."},"media_id":{"type":"string","description":"Existing media id (med_…)."},"filters":{"type":"string","description":"JSON-encoded filters object."},"territory_match":{"type":"string","enum":["protection","direct"],"description":"How filters.jurisdictions matches: protection (default) or direct."},"crop":{"type":"string","description":"JSON-encoded normalized crop box."},"limit":{"type":"string","description":"Bounded top-K page size (1-100)."},"channels":{"type":"string","description":"JSON-encoded array of §3.5 signal channels."}}},"SearchFeedbackResponse":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["search_feedback"]},"search_id":{"type":"string"},"action":{"type":"string","enum":["click","select","export"]},"created_at":{"type":"string"},"request_id":{"type":"string"}},"required":["id","object","search_id","action","created_at","request_id"]},"TrademarkSuggestion":{"type":"object","properties":{"id":{"type":"string","example":"tm_abc"},"object":{"type":"string","enum":["trademark_suggestion"]},"mark_text":{"type":["string","null"],"example":"SIGNA"},"office_code":{"type":["string","null"],"example":"US"},"status_stage":{"type":"string","example":"registered"}},"required":["id","object","mark_text","office_code","status_stage"]},"TrademarkSuggestResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkSuggestion"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"TrademarkDetailResponse":{"allOf":[{"$ref":"#/components/schemas/TrademarkDetailV1"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"TrademarkBatchResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkDetailV1"},"description":"One trademark per submitted id or identifier that matched, in input order; an item submitted twice appears twice."},"has_more":{"type":"boolean","enum":[false]},"pagination":{"type":"object","properties":{"cursor":{"type":"null"}},"required":["cursor"]},"not_found":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"application_number":{"type":"string","example":"97123456"},"registration_number":{"type":"string","example":"6789012"},"ir_number":{"type":"string","example":"1234567"},"office_code":{"type":"string","description":"Office code: WIPO ST.3 uppercase (e.g. US, EM); legacy acronym slugs (uspto, euipo) and EU are also accepted. Required with application_number or registration_number. Optional with ir_number: omitted, the lookup answers the IR record; given, that office's record of the IR.","example":"US"}},"additionalProperties":false}]},"description":"Submitted IDs (including malformed ones) or identifiers that did not match any trademark, echoed verbatim in input order. Every submitted item is in exactly one of `data` or `not_found`."},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","not_found","request_id"]},"TrademarkBatchRequest":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"description":"Array of trademark IDs (tm_...). Max 100.","example":["tm_abc123","tm_def456"]},"identifiers":{"type":"array","items":{"type":"object","properties":{"application_number":{"type":"string","example":"97123456"},"registration_number":{"type":"string","example":"6789012"},"ir_number":{"type":"string","example":"1234567"},"office_code":{"type":"string","description":"Office code: WIPO ST.3 uppercase (e.g. US, EM); legacy acronym slugs (uspto, euipo) and EU are also accepted. Required with application_number or registration_number. Optional with ir_number: omitted, the lookup answers the IR record; given, that office's record of the IR.","example":"US"}},"additionalProperties":false},"description":"Array of office-native identifiers. Max 100."},"include":{"type":"array","items":{"type":"string","enum":["office_extensions"]},"description":"Optional detail projections applied to every returned trademark. `office_extensions` includes raw office-specific blobs.","example":["office_extensions"]}},"additionalProperties":false},"Aggregations":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"integer"}}},"AggregationMetadata":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}},"example":{"entity_id":{"ent_a1b2c3d4":"8x8, Inc."}}},"SearchResponseV2":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkSummaryV1"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"search_meta":{"type":"object","properties":{"search_id":{"type":"string","example":"srch_abc123"},"query":{"type":["string","null"],"description":"Echo of the text query, or null for filter-only searches and for a q list.","example":"SIGNA"},"similarity_applied":{"type":"array","items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"The similarity channels q ran on (identical is always included). Empty without q.","example":["identical","fuzzy","embedded","lookalike"]},"ranking_version":{"type":"string","description":"Version of the ranking that ordered this response. Cursors are bound to it: a new version restarts pagination (400 `cursor_invalid`).","example":"v13"},"order":{"type":"string","description":"The order applied: `relevance` (q present), `mark_text_fit` (text order for a mark_text-only request), `filing_date` (newest filing first), or the explicit `sort` string.","example":"relevance"},"complete":{"type":"boolean","description":"False only when the search hit its time limit or lost a shard and the request set allow_partial; the page may then be missing matches. Without allow_partial such a search returns 503.","example":true},"incomplete_reason":{"type":"string","enum":["timeout","shard_failure"],"description":"Why `complete` is false. Omitted when complete.","example":"timeout"},"identifier":{"type":"object","properties":{"office":{"type":["string","null"],"description":"WIPO ST.3 code when q names or implies one office; null for a bare number.","example":"US"},"kind":{"type":"string","enum":["application","registration","ir","signa_id","number"],"example":"number"},"number":{"type":"string","description":"The number in the office's stored form (a tm_ id for signa_id).","example":"1939139"}},"required":["office","kind","number"],"description":"Present when q was read as a trademark number: those records are looked up besides the ranked text match and listed first."},"deprecations":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string","example":"strategies"},"replacement":{"type":"string","example":"similarity"},"sunset":{"type":"string","description":"Date (UTC) from which the deprecated parameter is rejected.","example":"2026-12-28"}},"required":["param","replacement","sunset"]},"description":"The deprecated parameters this request used, each with its replacement. Omitted when none."},"international_registrations":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation actually served. grouped = one row per mark/IR, coverage block present on IR rows; expanded = one row per Madrid designation. A trademark number in q is served expanded: one row per record it names.","example":"grouped"},"index_generation":{"type":["integer","null"],"description":"Generation of the search index that served this response (the grouped or the record index). Cursors are bound to it: after an index rebuild, a cursor from the previous generation returns 400 `cursor_invalid`; restart pagination. null when the generation could not be read (cursors then skip the check).","example":4},"territory_match":{"type":"string","enum":["protection","direct"],"description":"The jurisdictions match mode actually applied. protection (default) expands jurisdictions to protection scope (a EUTM matches a jurisdictions=FR request); direct matches literal territory legs only.","example":"protection"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable warning code for client handling: `<channel>_skipped` (a requested similarity channel produced no clauses for this query; see `channel`), `partial_opposition_coverage` / `partial_seniority_coverage` / `partial_owner_country_coverage` (filter coverage), `expanded_fallback` (a grouped request was served one row per record because the grouped view cannot serve a filter, sort or option; see `affected_filters` / `affected_option`), `identifier_lookup` (`q` is a trademark number, so the response lists the records it names, one row per record), `result_window_reached` (more than 10,000 rows match and this page is the last one the 10,000-row result window lets a relevance or sorted walk reach), `mixed_script` (a mark_text operator value mixes Latin with Greek or Cyrillic letters, which the operators compare as written; see `affected_filter`), `all_words_required` (a q of several words returned fewer than 5 rows in all; q generally requires its words to appear in the mark, so send q as a ranked list of shorter phrases to widen the search), `multi_word_retry_skipped` (the second search allowing a one-letter difference per word was skipped for time).","example":"phonetic_skipped"},"message":{"type":"string","description":"Human-readable explanation of the warning.","example":"phonetic_skipped: the phonetic similarity channel produced no clauses for this query."},"channel":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"],"description":"For `<channel>_skipped` warnings, the requested similarity channel that produced no clauses.","example":"phonetic"},"severity":{"type":"string","enum":["info","warning"],"description":"Warning severity (filter-coverage warnings).","example":"warning"},"affected_filter":{"type":"string","description":"Filter whose behavior is qualified by this warning.","example":"seniority_claims"},"affected_offices":{"type":"array","items":{"type":"string"},"description":"Office codes affected by the coverage or behavior caveat (WIPO ST.3, e.g. US, EM, WO).","example":["EM"]},"affected_filters":{"type":"array","items":{"type":"string"},"description":"For `expanded_fallback` warnings, the filter(s) the grouped view could not serve. Two entries mean the pair could hold on different designations of one mark.","example":["filing_date","status_primary"]},"affected_option":{"type":"string","description":"For `expanded_fallback` warnings, the option the grouped view could not serve: `sort`, `aggregations`, `aggregations_only` or `include_timing`.","example":"sort"},"behavior":{"type":"string","description":"Human-readable explanation of how the API behaves for the affected filter.","example":"Seniority claims are currently indexed from EUIPO only with low coverage; non-EUIPO records may appear as none or unknown."}},"required":["code","message"]},"description":"Coded search warnings: per-channel skip warnings (a REQUESTED similarity channel produced zero clauses for the query shape — e.g. similarity=phonetic on a query too short/high-collision), filter-coverage warnings (an applied filter, e.g. opposition_status, seniority_claims or owner_country, has partial index coverage), `expanded_fallback` (a grouped request was served one row per record), `identifier_lookup` (q is a trademark number, served one row per record it names), `result_window_reached` (the 10,000-row result window, not the data, ends this walk), `all_words_required` (a q of several words returned fewer than 5 rows in all; q generally requires its words to appear in the mark, so send q as a ranked list of shorter phrases to widen the search) and `multi_word_retry_skipped` (the second search allowing a one-letter difference per word was skipped for time). Omitted when there is nothing to warn about."},"execution_time_ms":{"type":"number","example":142},"timing":{"type":"object","properties":{"opensearch_ms":{"type":"number"},"serialization_ms":{"type":"number"},"overhead_ms":{"type":"number"}},"required":["opensearch_ms","serialization_ms","overhead_ms"],"description":"Per-phase timing breakdown (ms). Present only when options.include_timing=true."}},"required":["search_id","query","similarity_applied","ranking_version","order","complete","international_registrations","index_generation","territory_match","execution_time_ms"]},"aggregations":{"$ref":"#/components/schemas/Aggregations"},"aggregation_metadata":{"$ref":"#/components/schemas/AggregationMetadata"},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"MarkTextFilters":{"type":"object","properties":{"is":{"type":"array","items":{"type":"string"},"description":"Whole-mark equality (case, accents, punctuation, spacing and trademark notices ignored)."},"word":{"type":"array","items":{"type":"string"},"description":"The value appears as a whole word, or consecutive words, of the mark."},"starts_with":{"type":"array","items":{"type":"string"},"description":"The folded mark begins with the value."},"ends_with":{"type":"array","items":{"type":"string"},"description":"The folded mark ends with the value. At least 3 characters."},"contains":{"type":"array","items":{"type":"string"},"description":"The value appears anywhere in the folded mark. At least 3 characters."},"pattern":{"type":"array","items":{"type":"string"},"description":"`*` any run, `?` one character, `\\` escapes the next character; everything else literal."}},"additionalProperties":false,"description":"Mark text operators. Values within one operator are OR; operators are AND. Up to 100 values of 200 characters each."},"SearchExclude":{"type":"object","properties":{"mark_text":{"$ref":"#/components/schemas/MarkTextFilters"},"entity_id":{"type":"array","items":{"type":"string"},"description":"Exclude marks whose owners are linked to these entities (ent_...)."},"entity_group":{"type":"array","items":{"type":"string"},"description":"Exclude marks linked to any entity in these entities' corporate families (ent_...)."},"owner_id":{"type":"array","items":{"type":"string"},"description":"Exclude marks held by these owners (own_...)."},"trademark_ids":{"type":"array","items":{"type":"string"},"maxItems":1000,"description":"Exclude these trademarks (tm_...); on the grouped view, the family row containing them."}},"additionalProperties":false,"description":"Exclusions: rows matching any value are removed. Never affects ranking."},"TrademarkEvent":{"type":"object","properties":{"id":{"type":"string","example":"hst_7d4e1f2a-3b8c-4d0e-9f1a-2b3c4d5e6f70"},"object":{"type":"string","enum":["trademark_event"]},"event_date":{"type":["string","null"],"example":"2025-01-20"},"event_type":{"type":"string","description":"Signa's normalised event type.","example":"registration"},"raw":{"allOf":[{"$ref":"#/components/schemas/OfficeRawValue"},{"description":"The office's verbatim event code and label (label null when the stored text is Signa's wording); null when neither remains. Where Signa joined office fields into one label, `raw` carries those fields alone (for example INPI's `{\"code\": \"Inscription\", \"label\": \"Changement d'adresse\"}`)."}]},"description":{"type":["string","null"],"description":"Further text for the event beyond `raw`: office detail such as a recorded change, or, where `raw.label` is withheld because the wording is Signa's, that text (for example EUIPO's `Bulletin 2026/012 Section D.1` or IPOS's `Application filed`). Null when there is nothing beyond `raw`.","example":null},"event_scope":{"type":["string","null"],"example":"right"},"status_after_event":{"type":["string","null"],"example":"registered"},"nice_class":{"type":["integer","null"],"example":null},"territory_code":{"type":["string","null"],"example":null},"source_identifier":{"type":["string","null"],"example":null},"sequence_number":{"type":["integer","null"],"example":12}},"required":["id","object","event_date","event_type","raw","description","event_scope","status_after_event","nice_class","territory_code","source_identifier","sequence_number"]},"TrademarkEventsResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkEvent"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"TrademarkProceedingParty":{"type":"object","properties":{"owner_id":{"type":["string","null"],"example":"own_xyz"},"name":{"type":["string","null"],"example":"Opposing Corp"},"role":{"type":"string","example":"opponent"},"country_code":{"type":["string","null"],"example":"US"}},"required":["owner_id","name","role","country_code"]},"TrademarkProceedingSub":{"type":"object","properties":{"id":{"type":"string","example":"prc_abc"},"proceeding_type":{"type":"string","example":"opposition"},"proceeding_number":{"type":["string","null"],"example":"91234567"},"trademark_role":{"type":"string","enum":["contested","asserted"],"description":"This mark's side: `contested` when the proceeding targets it (it was opposed, petitioned for cancellation, or appealed), `asserted` when the opposer or petitioner pleaded it as a prior right.","example":"contested"},"status":{"type":["string","null"],"example":"pending"},"outcome":{"type":["string","null"],"enum":["challenger_won","challenger_lost","mixed","settled","withdrawn","default_judgment","pending","other",null],"description":"Normalized proceeding outcome from the challenger perspective.","example":"challenger_won"},"duration_days":{"type":["integer","null"],"description":"Decision date minus filed date in days. Null when either date is missing.","example":219},"filed_date":{"type":["string","null"],"example":"2025-03-01"},"decision_date":{"type":["string","null"],"example":null},"decision_outcome":{"type":["string","null"],"example":null},"parties":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkProceedingParty"}},"contested_classes":{"type":["array","null"],"items":{"type":"integer"},"example":[9,42]},"description":{"type":["string","null"],"example":null}},"required":["id","proceeding_type","proceeding_number","trademark_role","status","outcome","duration_days","filed_date","decision_date","decision_outcome","parties","contested_classes","description"]},"TrademarkProceedingsResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkProceedingSub"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"AssignmentParty":{"type":"object","properties":{"role":{"type":"string","enum":["assignor","assignee"],"example":"assignor"},"name":{"type":"string","example":"Assignor Corp"},"owner_id":{"type":["string","null"],"example":"own_abc123"},"execution_date":{"type":["string","null"],"example":"2024-01-15"},"date_acknowledged":{"type":["string","null"],"example":"2024-01-16"},"legal_entity_text":{"type":["string","null"],"example":"corporation"},"country_code":{"type":["string","null"],"description":"The party's nationality as an ISO 3166-1 alpha-2 code; null when the office named no country (e.g. a US state of organisation).","example":"US"},"address":{"$ref":"#/components/schemas/Address"}},"required":["role","name","owner_id","execution_date","date_acknowledged","legal_entity_text","country_code","address"]},"AssignmentProperty":{"type":"object","properties":{"trademark_id":{"type":["string","null"],"example":"tm_7d4e1f2a3b8c9d0e"},"application_number":{"type":"string","description":"USPTO serial number.","example":"97123456"},"registration_number":{"type":["string","null"],"example":"7234567"},"ir_number":{"type":["string","null"],"description":"Madrid international registration number.","example":null},"mark_text":{"type":["string","null"],"example":"SIGNA"}},"required":["trademark_id","application_number","registration_number","ir_number","mark_text"]},"Assignment":{"type":"object","properties":{"id":{"type":"string","example":"asg_7d4e1f2a3b8c9d0e"},"object":{"type":"string","enum":["assignment"]},"office_code":{"type":"string","enum":["US"],"description":"The recording office (WIPO ST.3). Recorded assignments are USPTO recordations."},"reel_number":{"type":"string","example":"1234"},"frame_number":{"type":"string","example":"5678"},"conveyance_type":{"type":"string","enum":["assignment","security_interest","release","merger","name_change","license","partial_assignment","correction","entity_conversion","other"],"example":"assignment"},"conveyance_text":{"type":"string","example":"ASSIGNS THE ENTIRE INTEREST"},"recorded_date":{"type":["string","null"],"example":"2024-01-15"},"last_update_date":{"type":["string","null"],"example":"2024-01-16"},"page_count":{"type":["integer","null"],"example":3},"release_of_reel_number":{"type":["string","null"],"example":null},"release_of_frame_number":{"type":["string","null"],"example":null},"release_match":{"type":["string","null"],"enum":["pointer",null],"description":"Security interests only: `pointer` when a release cites this recording's reel/frame, in its `release_of_*` fields or in its text (the release then also covers one of this recording's marks). `null` when no release cites it: the lien reads as open. Releases that cite no reel/frame are not paired yet. Always `null` for other conveyance types.","example":null},"created_at":{"type":"string","example":"2024-01-15T12:00:00.000Z"},"updated_at":{"type":"string","example":"2024-01-15T12:00:00.000Z"}},"required":["id","object","office_code","reel_number","frame_number","conveyance_type","conveyance_text","recorded_date","last_update_date","page_count","release_of_reel_number","release_of_frame_number","release_match","created_at","updated_at"]},"TrademarkAssignmentSub":{"allOf":[{"$ref":"#/components/schemas/Assignment"},{"type":"object","properties":{"correspondent":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{}},{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}],"example":{"name":"Jane Correspondent"}},"parties":{"type":"array","items":{"$ref":"#/components/schemas/AssignmentParty"}},"properties":{"type":"array","items":{"$ref":"#/components/schemas/AssignmentProperty"}}},"required":["correspondent","parties","properties"]}]},"TrademarkAssignmentsResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkAssignmentSub"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"TrademarkDocument":{"type":"object","properties":{"id":{"type":"string","example":"med_019d2141-6ce9-771b-872e-bc8b20e49fcf"},"object":{"type":"string","enum":["trademark_document"]},"document_kind":{"type":"string","enum":["office_action","certificate","correspondence","filed_form","other"],"example":"office_action"},"official_date":{"type":["string","null"],"example":"2025-11-04"},"description":{"type":["string","null"],"example":"Non-final Office Action"},"mime_type":{"type":"string","example":"application/pdf"},"page_count":{"type":["integer","null"],"example":12},"url":{"type":"string","format":"uri","example":"https://api.signa.so/v1/trademarks/tm_abc/media/med_019d2141-6ce9-771b-872e-bc8b20e49fcf"}},"required":["id","object","document_kind","official_date","description","mime_type","page_count","url"]},"TrademarkDocumentSourceSync":{"type":"object","properties":{"status":{"type":"string","enum":["synced","pending","unsupported"],"example":"synced"},"last_synced_at":{"type":["string","null"],"example":"2026-07-05T12:00:00.000Z"}},"required":["status","last_synced_at"]},"TrademarkDocumentsResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkDocument"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"source_sync":{"$ref":"#/components/schemas/TrademarkDocumentSourceSync"},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","source_sync","request_id"]},"CitationTrademarkSummary":{"type":"object","properties":{"id":{"type":"string","example":"tm_7d4e1f2a3b8c9d0e"},"mark_text":{"type":["string","null"],"example":"ACME"},"office_code":{"type":["string","null"],"description":"Registering office in WIPO ST.3 (uppercase). Null when unknown.","example":"US"},"application_number":{"type":["string","null"],"example":"98123456"},"registration_number":{"type":["string","null"],"example":"5567890"},"status_primary":{"type":"string","example":"active"}},"required":["id","mark_text","office_code","application_number","registration_number","status_primary"]},"Citation":{"type":"object","properties":{"id":{"type":"string","example":"cit_0198c2f1-7e2a-7b34-9c11-3d5f8a2b4c6e"},"object":{"type":"string","enum":["citation"]},"office_code":{"type":["string","null"],"description":"Office that issued the action, WIPO ST.3 (uppercase).","example":"US"},"application_ref":{"type":"string","description":"Application number the office action was issued against, as cited by the office.","example":"98123456"},"trademark":{"anyOf":[{"$ref":"#/components/schemas/CitationTrademarkSummary"},{"type":"null"}],"description":"The citing application, when it is on our register."},"cited_ref":{"type":"string","description":"The prior mark reference cited by the examiner.","example":"5567890"},"cited_ref_type":{"type":"string","enum":["registration","application"],"description":"Whether `cited_ref` is a `registration` or an `application` number. This label is inferred from how the citing office action worded the reference, and it is occasionally wrong (a serial labelled as a registration, or the reverse). Resolution matches the number against both namespaces regardless of the label, so a mislabelled reference still resolves. Treat `cited_ref_type` as a hint; when `cited_trademark` is present it is the authoritative identification of the cited mark.","example":"registration"},"cited_trademark":{"anyOf":[{"$ref":"#/components/schemas/CitationTrademarkSummary"},{"type":"null"}],"description":"The cited prior mark, when it is on our register. Null means the citation is matched by reference only."},"refusal_type":{"type":"string","enum":["2d"],"description":"Office-local refusal ground vocabulary (USPTO `2d` = §2(d) likelihood of confusion).","example":"2d"},"action_date":{"type":["string","null"],"description":"Office action date (YYYY-MM-DD).","example":"2026-01-15"},"action_stage":{"type":["string","null"],"enum":["nonfinal","final",null],"description":"The stage the citation REACHED, not provenance about `source_document_id`. A citation first raised in a nonfinal action reads `final` once a later dated final action maintained the refusal, so `final` does not mean the row was extracted from a final action.","example":"final"},"disposition":{"type":["string","null"],"enum":["citation_issued","maintained","withdrawn","abandoned_after","published",null],"description":"How the citation resolved. Null while pending the daily disposition refresh.","example":"maintained"},"disposition_at":{"type":["string","null"],"description":"When the current `disposition` was first derived or last changed. It does NOT advance when a daily run re-derives the same value, so a stale-looking timestamp means the disposition has been stable, not that the refresh stopped running.","example":"2026-08-30T13:30:00Z"},"source_document_id":{"type":["string","null"],"description":"Office action the citation was extracted from. Every citation served today carries one; the field is nullable so a citation derived without a stored source document can be represented.","example":"med_0198c2f1-7e2a-7b34-9c11-3d5f8a2b4c6e"}},"required":["id","object","office_code","application_ref","trademark","cited_ref","cited_ref_type","cited_trademark","refusal_type","action_date","action_stage","disposition","disposition_at","source_document_id"]},"CitationListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Citation"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"AnalyticsPortfolioBlock":{"type":"object","properties":{"mark_count":{"type":"integer"},"active_count":{"type":"integer"},"dead_count":{"type":"integer"},"unknown_count":{"type":"integer","description":"Marks whose status stage is unknown: active_count + dead_count + unknown_count = mark_count."},"status_distribution":{"type":"object","additionalProperties":{"type":"number"}},"class_distribution":{"type":"object","additionalProperties":{"type":"number"}},"jurisdiction_spread":{"type":"object","additionalProperties":{"type":"number"}},"filing_trend":{"type":"object","additionalProperties":{"type":"number"}}},"required":["mark_count","active_count","dead_count","unknown_count","status_distribution","class_distribution","jurisdiction_spread","filing_trend"]},"AnalyticsSideStats":{"type":"object","properties":{"total":{"type":"integer"},"by_type":{"type":"object","additionalProperties":{"type":"number"}},"outcomes":{"type":"object","additionalProperties":{"type":"number"}},"decided":{"type":"integer"},"win_rate":{"type":["number","null"]},"avg_duration_days":{"type":["number","null"]}},"required":["total","by_type","outcomes","decided","win_rate","avg_duration_days"]},"AnalyticsLitigationBlock":{"type":["object","null"],"properties":{"subject":{"type":"object","properties":{"owner_id":{"type":["string","null"]},"entity_id":{"type":["string","null"]}},"required":["owner_id","entity_id"]},"proceedings_total":{"type":"integer"},"as_challenger":{"$ref":"#/components/schemas/AnalyticsSideStats"},"as_defendant":{"$ref":"#/components/schemas/AnalyticsSideStats"}},"required":["subject","proceedings_total","as_challenger","as_defendant"],"example":{"subject":{"owner_id":"own_01HZX3K7Q8M9N0P1R2S3T4V5W6","entity_id":null},"proceedings_total":3,"as_challenger":{"total":2,"by_type":{"opposition":1,"cancellation":1},"outcomes":{"challenger_won":1,"settled":1},"decided":1,"win_rate":1,"avg_duration_days":124.5},"as_defendant":{"total":1,"by_type":{"opposition":1},"outcomes":{"challenger_lost":1},"decided":1,"win_rate":1,"avg_duration_days":87}}},"AnalyticsTransactionsBlock":{"type":["object","null"],"properties":{"transaction_count":{"type":"integer"},"by_type":{"type":"object","additionalProperties":{"type":"number"}},"unreleased_security_interests":{"type":"integer"},"marks_with_liens":{"type":"integer"},"acquired_count":{"type":"integer"},"divested_count":{"type":"integer"},"first_transaction_date":{"type":["string","null"]},"last_transaction_date":{"type":["string","null"]}},"required":["transaction_count","by_type","unreleased_security_interests","marks_with_liens","acquired_count","divested_count","first_transaction_date","last_transaction_date"],"example":{"transaction_count":4,"by_type":{"assignment":2,"security_interest":1,"release":1},"unreleased_security_interests":0,"marks_with_liens":0,"acquired_count":2,"divested_count":1,"first_transaction_date":"2019-06-15","last_transaction_date":"2024-03-01"}},"AnalyticsReport":{"type":"object","properties":{"object":{"type":"string","enum":["analytics_report"]},"subject":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["owner","attorney","firm","entity"]},"name":{"type":"string"}},"required":["id","object","name"]},"portfolio":{"$ref":"#/components/schemas/AnalyticsPortfolioBlock"},"litigation":{"$ref":"#/components/schemas/AnalyticsLitigationBlock"},"transactions":{"$ref":"#/components/schemas/AnalyticsTransactionsBlock"},"generated_at":{"type":"string"}},"required":["object","subject","portfolio","litigation","transactions","generated_at"]},"AnalyticsReportResponse":{"allOf":[{"$ref":"#/components/schemas/AnalyticsReport"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"OfficeAnalytics":{"type":"object","properties":{"object":{"type":"string","enum":["office_analytics"]},"code":{"type":"string","description":"WIPO ST.3 office code.","example":"US"},"total_marks":{"type":"number"},"registered_count":{"type":"number"},"pending_count":{"type":"number"},"expired_count":{"type":"number"},"cancelled_count":{"type":"number"},"abandoned_count":{"type":"number"},"unknown_count":{"type":"integer","description":"Records whose status stage is unknown, the sixth status bucket: the six bucket counts sum to total_marks."},"registration_rate":{"type":["number","null"]},"jurisdiction_count":{"type":"number"},"earliest_filing_date":{"type":["string","null"]},"latest_filing_date":{"type":["string","null"]},"top_classes":{"type":["array","null"],"items":{"type":"object","properties":{"class":{"type":"number"},"count":{"type":"number"},"pct":{"type":"number"}},"required":["class","count","pct"]}},"yearly_trend":{"type":["array","null"],"items":{"type":"object","properties":{"year":{"type":"number"},"filed":{"type":"number"},"registered":{"type":"number"},"abandoned":{"type":"number"}},"required":["year","filed","registered","abandoned"]}},"stats_computed_at":{"type":"string"}},"required":["object","code","total_marks","registered_count","pending_count","expired_count","cancelled_count","abandoned_count","unknown_count","registration_rate","jurisdiction_count","earliest_filing_date","latest_filing_date","top_classes","yearly_trend","stats_computed_at"]},"OfficeAnalyticsResponse":{"allOf":[{"$ref":"#/components/schemas/OfficeAnalytics"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"MarketAnalytics":{"type":"object","properties":{"object":{"type":"string","enum":["market_analytics"]},"total_marks":{"type":"number"},"active_count":{"type":"number"},"by_status":{"type":"object","properties":{"registered":{"type":"number"},"pending":{"type":"number"},"expired":{"type":"number"},"cancelled":{"type":"number"},"abandoned":{"type":"number"}},"required":["registered","pending","expired","cancelled","abandoned"],"description":"Records per status bucket. Every status stage is in exactly one bucket: pending holds every stage before registration (opposition_period included), registered includes pending_cancellation, cancelled includes surrendered and invalidated, abandoned includes withdrawn and refused. The sixth bucket, unknown, is unknown_count."},"unknown_count":{"type":["integer","null"],"description":"Records whose status stage is unknown, the sixth status bucket: by_status plus unknown_count sums to total_marks. null on stats computed before this count existed, until the next recompute."},"by_office":{"type":"object","additionalProperties":{},"description":"Per-office breakdown keyed by WIPO ST.3 office code (e.g. US, EM, WO).","example":{"US":60,"EM":25}},"top_classes":{"type":"array","items":{"type":"object","properties":{"class":{"type":"number"},"count":{"type":"number"},"pct":{"type":"number"}},"required":["class","count","pct"]}},"filing_trend":{"type":"object","additionalProperties":{}},"computed_at":{"type":"string"}},"required":["object","total_marks","active_count","by_status","unknown_count","by_office","top_classes","filing_trend","computed_at"]},"MarketAnalyticsResponse":{"allOf":[{"$ref":"#/components/schemas/MarketAnalytics"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"ClassificationAnalytics":{"type":"object","properties":{"object":{"type":"string","enum":["classification_analytics"]},"nice_class":{"type":"number"},"total_marks":{"type":"number"},"active_count":{"type":"number"},"by_status":{"type":"object","properties":{"registered":{"type":"number"},"pending":{"type":"number"},"expired":{"type":"number"},"cancelled":{"type":"number"},"abandoned":{"type":"number"}},"required":["registered","pending","expired","cancelled","abandoned"],"description":"Records per status bucket. Every status stage is in exactly one bucket: pending holds every stage before registration (opposition_period included), registered includes pending_cancellation, cancelled includes surrendered and invalidated, abandoned includes withdrawn and refused. The sixth bucket, unknown, is unknown_count."},"unknown_count":{"type":["integer","null"],"description":"Records whose status stage is unknown, the sixth status bucket: by_status plus unknown_count sums to total_marks. null on stats computed before this count existed, until the next recompute."},"by_office":{"type":"object","additionalProperties":{},"description":"Per-office breakdown keyed by WIPO ST.3 office code (e.g. US, EM, WO).","example":{"US":60,"EM":25}},"filing_trend":{"type":"object","additionalProperties":{}},"computed_at":{"type":"string"}},"required":["object","nice_class","total_marks","active_count","by_status","unknown_count","by_office","filing_trend","computed_at"]},"ClassificationAnalyticsResponse":{"allOf":[{"$ref":"#/components/schemas/ClassificationAnalytics"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"Owner":{"type":"object","properties":{"id":{"type":"string","example":"own_a1b2c3d4"},"object":{"type":"string","enum":["owner"]},"name":{"type":"string","description":"Display name (falls back to canonical_name when no display_name is set).","example":"Apple Inc."},"canonical_name":{"type":"string","example":"APPLE INC"},"name_original_script":{"type":["string","null"],"description":"CJK/Arabic original-script name. null for Latin-script owners."},"country_code":{"type":["string","null"],"example":"US"},"legal_form":{"type":["string","null"],"description":"The kind of legal person, normalised from the office's entity-type code; null when the office states none.","example":"corporation"},"address":{"$ref":"#/components/schemas/Address"},"entity_id":{"type":["string","null"],"description":"The resolved entity this owner is linked into (GET /v1/entities/{id}). null when the owner is not linked to an entity.","example":"ent_a1b2c3d4"},"publicly_traded":{"type":"boolean","description":"Whether the owner's company links include an active SEC company with a ticker. For an owner linked to an entity, the entity's `publicly_traded`: any active SEC company with a ticker across members, or the entity itself is listed or a subsidiary of a listed company."},"ticker":{"type":["string","null"],"description":"The owner's own first SEC ticker. When it has none and is linked to an entity, the entity's `ticker`, which can be a ticker inherited from a listed ancestor. null when none.","example":"AAPL"},"lei":{"type":["string","null"],"description":"The owner's own first GLEIF LEI, uppercased. When it has none and is linked to an entity, the entity's `lei`: its own LEI when set, else the first GLEIF LEI across members. null when none.","example":"HWUPKR0MPOU8FGXBT394"},"has_lei":{"type":"boolean","description":"Whether the owner's company links include a GLEIF LEI. For an owner linked to an entity, the entity's `has_lei`: its own LEI, or any GLEIF LEI across members."},"companies_source":{"type":"string","enum":["entity","direct"],"description":"`entity` when company facts are inherited across entity members; `direct` when the owner is not linked, or its entity is no longer served (GET /v1/entities/{id} returns 404), and the facts are its own links only.","example":"entity"},"trademark_count":{"type":"integer","description":"Distinct marks (mark grain): a Madrid IR and its designations count once, matching the default grouped trademark listings. 0 when stats are not yet computed.","example":1024},"active_count":{"type":"integer","description":"Distinct marks (mark grain) that are registered or still in prosecution. Always present; 0 when stats are not yet computed.","example":640},"aliases":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","description":"variant | translation | abbreviation | former_name"},"source_office_code":{"type":["string","null"],"description":"WIPO ST.3 code of the office that recorded this alias."}},"required":["name","type","source_office_code"]}},"identifiers":{"type":"array","items":{"type":"object","properties":{"office_code":{"type":["string","null"]},"identifier":{"type":"string"},"identifier_type":{"type":"string"}},"required":["office_code","identifier","identifier_type"]}},"companies":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","example":"sec"},"source_id":{"type":"string","example":"0000320193"},"legal_name":{"type":"string","example":"Apple Inc."},"ticker":{"type":["string","null"],"example":"AAPL"},"exchange":{"type":["string","null"],"example":"NASDAQ"},"lei":{"type":["string","null"],"example":"HWUPKR0MPOU8FGXBT394"},"entity_status":{"type":"string","enum":["active","inactive","delisted"],"example":"active"},"confidence":{"type":"number","description":"Match confidence in [0,1]."},"verified_at":{"type":["string","null"],"description":"ISO 8601 timestamp when the match was manually verified."},"verified_by":{"type":["string","null"],"description":"User or system that verified the match."}},"required":["source","source_id","legal_name","ticker","exchange","lei","entity_status"]},"description":"Omitted entirely when empty. When the owner is linked to an entity this is the union of all members' company links (served through the entity), the owner's own links first."},"stats":{"type":["object","null"],"properties":{"trademark_count":{"type":"integer","description":"Distinct marks (mark grain): a Madrid IR and its designations count once, matching the default grouped trademark listings. 0 when stats are not yet computed."},"registered_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count. Includes records whose cancellation is pending (pending_cancellation): they stay registered until it is decided."},"pending_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count. Every stage before registration, including opposition_period and allowed."},"expired_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count."},"cancelled_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count. Includes surrendered and invalidated records."},"abandoned_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count. Includes withdrawn and refused records."},"unknown_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count. Records whose office status is not known (status stage unknown)."},"registration_rate":{"type":["number","null"],"description":"Deprecated: use grant_rate. Same value; registration_rate is a misnomer (it is the share of concluded prosecutions that were ever granted, not the share currently registered).","deprecated":true},"grant_rate":{"type":["number","null"],"description":"Share of concluded prosecutions (registered + expired + cancelled) that were ever granted, over office records (record grain). Same value as the deprecated registration_rate."},"abandonment_rate":{"type":["number","null"],"description":"Share of concluded prosecutions (record grain) that ended abandoned, withdrawn or refused: abandoned / (registered + expired + cancelled + abandoned)."},"jurisdiction_count":{"type":"integer","description":"Distinct offices among the records. A Madrid IR's designations recorded by WIPO count as one office."},"earliest_filing_date":{"type":["string","null"],"description":"Earliest filing_date over the records (YYYY-MM-DD)."},"latest_filing_date":{"type":["string","null"],"description":"Latest filing_date over the records (YYYY-MM-DD)."},"computed_at":{"type":["string","null"],"description":"When this stats row was last recomputed. The row only changes when a value changes, so an unchanged portfolio keeps its earlier stamp."}},"required":["trademark_count","registered_count","pending_count","expired_count","cancelled_count","abandoned_count","unknown_count","registration_rate","grant_rate","abandonment_rate","jurisdiction_count","earliest_filing_date","latest_filing_date","computed_at"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","canonical_name","name_original_script","country_code","legal_form","address","entity_id","publicly_traded","ticker","lei","has_lei","companies_source","trademark_count","active_count","aliases","identifiers","stats","created_at","updated_at"]},"OwnerResponse":{"allOf":[{"$ref":"#/components/schemas/Owner"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"OwnerSummary":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["owner"]},"name":{"type":"string"},"canonical_name":{"type":"string"},"country_code":{"type":["string","null"]},"legal_form":{"type":["string","null"],"description":"The kind of legal person, normalised from the office's entity-type code; null when the office states none.","example":"corporation"},"trademark_count":{"type":"integer","description":"Distinct marks (mark grain): a Madrid IR and its designations count once, matching the default grouped trademark listings. 0 when stats are not yet computed."},"active_count":{"type":"integer","description":"Distinct marks (mark grain) that are registered or still in prosecution. Always present; 0 when stats are not yet computed."},"entity_id":{"type":["string","null"],"description":"The resolved entity this owner is linked into. null when the owner is not linked to an entity.","example":"ent_a1b2c3d4"}},"required":["id","object","name","canonical_name","country_code","legal_form","trademark_count","active_count","entity_id"]},"OwnerListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/OwnerSummary"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"OwnerTrademarksV1Response":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkSummaryV1"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"search_meta":{"type":"object","properties":{"search_id":{"type":"string","example":"srch_abc123"},"query":{"type":["string","null"],"description":"Echo of the text query, or null for filter-only searches and for a q list.","example":"SIGNA"},"similarity_applied":{"type":"array","items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"The similarity channels q ran on (identical is always included). Empty without q.","example":["identical","fuzzy","embedded","lookalike"]},"ranking_version":{"type":"string","description":"Version of the ranking that ordered this response. Cursors are bound to it: a new version restarts pagination (400 `cursor_invalid`).","example":"v13"},"order":{"type":"string","description":"The order applied: `relevance` (q present), `mark_text_fit` (text order for a mark_text-only request), `filing_date` (newest filing first), or the explicit `sort` string.","example":"relevance"},"complete":{"type":"boolean","description":"False only when the search hit its time limit or lost a shard and the request set allow_partial; the page may then be missing matches. Without allow_partial such a search returns 503.","example":true},"incomplete_reason":{"type":"string","enum":["timeout","shard_failure"],"description":"Why `complete` is false. Omitted when complete.","example":"timeout"},"identifier":{"type":"object","properties":{"office":{"type":["string","null"],"description":"WIPO ST.3 code when q names or implies one office; null for a bare number.","example":"US"},"kind":{"type":"string","enum":["application","registration","ir","signa_id","number"],"example":"number"},"number":{"type":"string","description":"The number in the office's stored form (a tm_ id for signa_id).","example":"1939139"}},"required":["office","kind","number"],"description":"Present when q was read as a trademark number: those records are looked up besides the ranked text match and listed first."},"deprecations":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string","example":"strategies"},"replacement":{"type":"string","example":"similarity"},"sunset":{"type":"string","description":"Date (UTC) from which the deprecated parameter is rejected.","example":"2026-12-28"}},"required":["param","replacement","sunset"]},"description":"The deprecated parameters this request used, each with its replacement. Omitted when none."},"international_registrations":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation actually served. grouped = one row per mark/IR, coverage block present on IR rows; expanded = one row per Madrid designation. A trademark number in q is served expanded: one row per record it names.","example":"grouped"},"index_generation":{"type":["integer","null"],"description":"Generation of the search index that served this response (the grouped or the record index). Cursors are bound to it: after an index rebuild, a cursor from the previous generation returns 400 `cursor_invalid`; restart pagination. null when the generation could not be read (cursors then skip the check).","example":4},"territory_match":{"type":"string","enum":["protection","direct"],"description":"The jurisdictions match mode actually applied. protection (default) expands jurisdictions to protection scope (a EUTM matches a jurisdictions=FR request); direct matches literal territory legs only.","example":"protection"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable warning code for client handling: `<channel>_skipped` (a requested similarity channel produced no clauses for this query; see `channel`), `partial_opposition_coverage` / `partial_seniority_coverage` / `partial_owner_country_coverage` (filter coverage), `expanded_fallback` (a grouped request was served one row per record because the grouped view cannot serve a filter, sort or option; see `affected_filters` / `affected_option`), `identifier_lookup` (`q` is a trademark number, so the response lists the records it names, one row per record), `result_window_reached` (more than 10,000 rows match and this page is the last one the 10,000-row result window lets a relevance or sorted walk reach), `mixed_script` (a mark_text operator value mixes Latin with Greek or Cyrillic letters, which the operators compare as written; see `affected_filter`), `all_words_required` (a q of several words returned fewer than 5 rows in all; q generally requires its words to appear in the mark, so send q as a ranked list of shorter phrases to widen the search), `multi_word_retry_skipped` (the second search allowing a one-letter difference per word was skipped for time).","example":"phonetic_skipped"},"message":{"type":"string","description":"Human-readable explanation of the warning.","example":"phonetic_skipped: the phonetic similarity channel produced no clauses for this query."},"channel":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"],"description":"For `<channel>_skipped` warnings, the requested similarity channel that produced no clauses.","example":"phonetic"},"severity":{"type":"string","enum":["info","warning"],"description":"Warning severity (filter-coverage warnings).","example":"warning"},"affected_filter":{"type":"string","description":"Filter whose behavior is qualified by this warning.","example":"seniority_claims"},"affected_offices":{"type":"array","items":{"type":"string"},"description":"Office codes affected by the coverage or behavior caveat (WIPO ST.3, e.g. US, EM, WO).","example":["EM"]},"affected_filters":{"type":"array","items":{"type":"string"},"description":"For `expanded_fallback` warnings, the filter(s) the grouped view could not serve. Two entries mean the pair could hold on different designations of one mark.","example":["filing_date","status_primary"]},"affected_option":{"type":"string","description":"For `expanded_fallback` warnings, the option the grouped view could not serve: `sort`, `aggregations`, `aggregations_only` or `include_timing`.","example":"sort"},"behavior":{"type":"string","description":"Human-readable explanation of how the API behaves for the affected filter.","example":"Seniority claims are currently indexed from EUIPO only with low coverage; non-EUIPO records may appear as none or unknown."}},"required":["code","message"]},"description":"Coded search warnings: per-channel skip warnings (a REQUESTED similarity channel produced zero clauses for the query shape — e.g. similarity=phonetic on a query too short/high-collision), filter-coverage warnings (an applied filter, e.g. opposition_status, seniority_claims or owner_country, has partial index coverage), `expanded_fallback` (a grouped request was served one row per record), `identifier_lookup` (q is a trademark number, served one row per record it names), `result_window_reached` (the 10,000-row result window, not the data, ends this walk), `all_words_required` (a q of several words returned fewer than 5 rows in all; q generally requires its words to appear in the mark, so send q as a ranked list of shorter phrases to widen the search) and `multi_word_retry_skipped` (the second search allowing a one-letter difference per word was skipped for time). Omitted when there is nothing to warn about."},"execution_time_ms":{"type":"number","example":142},"timing":{"type":"object","properties":{"opensearch_ms":{"type":"number"},"serialization_ms":{"type":"number"},"overhead_ms":{"type":"number"}},"required":["opensearch_ms","serialization_ms","overhead_ms"],"description":"Per-phase timing breakdown (ms). Present only when options.include_timing=true."}},"required":["search_id","query","similarity_applied","ranking_version","order","complete","international_registrations","index_generation","territory_match","execution_time_ms"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"OwnerRelated":{"type":"object","properties":{"related_owner_id":{"type":"string","example":"own_xyz"},"name":{"type":"string","example":"Apple Operations International Ltd."},"country_code":{"type":["string","null"],"example":"IE"},"relationship_type":{"type":"string","example":"IS_DIRECTLY_CONSOLIDATED_BY"},"relationship_status":{"type":"string","example":"ACTIVE"},"ownership_pct":{"type":["number","null"],"example":100},"period_start":{"type":["string","null"],"example":"2015-06-01"},"period_end":{"type":["string","null"],"example":null},"direction":{"type":"string","enum":["child","parent"],"example":"child"},"source":{"type":"string","enum":["gleif_level2"],"example":"gleif_level2"}},"required":["related_owner_id","name","country_code","relationship_type","relationship_status","ownership_pct","period_start","period_end","direction","source"]},"OwnerRelatedResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/OwnerRelated"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"AttorneyFirm":{"type":"object","properties":{"id":{"type":"string","example":"firm_a1b2c3d4"},"name":{"type":"string","example":"Smith & Associates LLP"},"trademark_count":{"type":"integer","description":"Trademarks whose current filing names this attorney with this firm. Madrid designations count once per international registration, as the attorney's trademark_count.","example":42},"latest_filing_date":{"type":["string","null"],"description":"Newest filing date among those trademarks; null when none is dated.","example":"2026-05-01"}},"required":["id","name","trademark_count","latest_filing_date"]},"Attorney":{"type":"object","properties":{"id":{"type":"string","example":"att_a1b2c3d4"},"object":{"type":"string","enum":["attorney"]},"name":{"type":"string","description":"Display name (falls back to canonical_name when no display_name is set).","example":"Jane Smith"},"canonical_name":{"type":"string","example":"JANE SMITH"},"firm_id":{"type":["string","null"],"description":"Firm on the attorney's most recent current filing (by filing date) that names a firm; null when none does. Deprecated: use firms[].","example":"firm_a1b2c3d4","deprecated":true},"firm_name":{"type":["string","null"],"description":"Firm on the attorney's most recent current filing (by filing date) that names a firm; null when none does. Deprecated: use firms[].","example":"Smith & Associates LLP","deprecated":true},"firms":{"type":"array","items":{"$ref":"#/components/schemas/AttorneyFirm"},"description":"Firms named on the attorney's current filings, most trademarks first, at most 20; the firm in firm_id is appended when it ranks lower. Empty when no filing names a firm."},"country_code":{"type":["string","null"],"example":"US"},"source_office_code":{"type":["string","null"],"description":"WIPO ST.3 code of the office whose records this attorney row comes from. Attorney records are per office: the same person appears once per office they file at.","example":"US"},"trademark_count":{"type":"integer","description":"Distinct marks (mark grain): a Madrid IR and its designations count once, matching the default grouped trademark listings. 0 when stats are not yet computed.","example":512},"active_count":{"type":"integer","description":"Distinct marks (mark grain) that are registered or still in prosecution. Always present; 0 when stats are not yet computed.","example":300},"address":{"$ref":"#/components/schemas/Address"},"aliases":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","description":"variant | translation | abbreviation | former_name"},"source_office_code":{"type":["string","null"],"description":"WIPO ST.3 code of the office that recorded this alias."}},"required":["name","type","source_office_code"]}},"identifiers":{"type":"array","items":{"type":"object","properties":{"office_code":{"type":["string","null"]},"identifier":{"type":"string"},"identifier_type":{"type":"string"}},"required":["office_code","identifier","identifier_type"]}},"stats":{"type":["object","null"],"properties":{"trademark_count":{"type":"integer","description":"Distinct marks (mark grain): a Madrid IR and its designations count once, matching the default grouped trademark listings. 0 when stats are not yet computed."},"registered_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count. Includes records whose cancellation is pending (pending_cancellation): they stay registered until it is decided."},"pending_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count. Every stage before registration, including opposition_period and allowed."},"expired_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count."},"cancelled_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count. Includes surrendered and invalidated records."},"abandoned_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count. Includes withdrawn and refused records."},"unknown_count":{"type":"integer","description":"Office records (record grain) in this status bucket. Every record is in exactly one of the six buckets (registered, pending, expired, cancelled, abandoned, unknown), so the six counts sum to the records counted. A Madrid IR counts once per designation record, so the counts can sum to more than trademark_count. Records whose office status is not known (status stage unknown)."},"registration_rate":{"type":["number","null"],"description":"Deprecated: use grant_rate. Same value; registration_rate is a misnomer (it is the share of concluded prosecutions that were ever granted, not the share currently registered).","deprecated":true},"grant_rate":{"type":["number","null"],"description":"Share of concluded prosecutions (registered + expired + cancelled) that were ever granted, over office records (record grain). Same value as the deprecated registration_rate."},"abandonment_rate":{"type":["number","null"],"description":"Share of concluded prosecutions (record grain) that ended abandoned, withdrawn or refused: abandoned / (registered + expired + cancelled + abandoned)."},"jurisdiction_count":{"type":"integer","description":"Distinct offices among the records. A Madrid IR's designations recorded by WIPO count as one office."},"earliest_filing_date":{"type":["string","null"],"description":"Earliest filing_date over the records (YYYY-MM-DD)."},"latest_filing_date":{"type":["string","null"],"description":"Latest filing_date over the records (YYYY-MM-DD)."},"avg_prosecution_days":{"type":["number","null"],"description":"Mean days from filing_date to registration_date over records with both dates (record grain). null when no record has both."},"computed_at":{"type":["string","null"],"description":"When this stats row was last recomputed. The row only changes when a value changes, so an unchanged portfolio keeps its earlier stamp."}},"required":["trademark_count","registered_count","pending_count","expired_count","cancelled_count","abandoned_count","unknown_count","registration_rate","grant_rate","abandonment_rate","jurisdiction_count","earliest_filing_date","latest_filing_date","avg_prosecution_days","computed_at"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","canonical_name","firm_id","firm_name","firms","country_code","source_office_code","trademark_count","active_count","address","aliases","identifiers","stats","created_at","updated_at"]},"AttorneyResponse":{"allOf":[{"$ref":"#/components/schemas/Attorney"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"AttorneySummary":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["attorney"]},"name":{"type":"string"},"canonical_name":{"type":"string"},"firm_name":{"type":["string","null"],"description":"Firm on the attorney's most recent current filing (by filing date) that names a firm; null when none does."},"country_code":{"type":["string","null"]},"source_office_code":{"type":["string","null"],"description":"WIPO ST.3 code of the office whose records this attorney row comes from. Attorney records are per office: the same person appears once per office they file at.","example":"US"},"trademark_count":{"type":"integer","description":"Distinct marks (mark grain): a Madrid IR and its designations count once, matching the default grouped trademark listings. 0 when stats are not yet computed."},"active_count":{"type":"integer","description":"Distinct marks (mark grain) that are registered or still in prosecution. Always present; 0 when stats are not yet computed."}},"required":["id","object","name","canonical_name","firm_name","country_code","source_office_code","trademark_count","active_count"]},"AttorneyListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AttorneySummary"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"AttorneyTrademarksV1Response":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkSummaryV1"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"search_meta":{"type":"object","properties":{"search_id":{"type":"string","example":"srch_abc123"},"query":{"type":["string","null"],"description":"Echo of the text query, or null for filter-only searches and for a q list.","example":"SIGNA"},"similarity_applied":{"type":"array","items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"The similarity channels q ran on (identical is always included). Empty without q.","example":["identical","fuzzy","embedded","lookalike"]},"ranking_version":{"type":"string","description":"Version of the ranking that ordered this response. Cursors are bound to it: a new version restarts pagination (400 `cursor_invalid`).","example":"v13"},"order":{"type":"string","description":"The order applied: `relevance` (q present), `mark_text_fit` (text order for a mark_text-only request), `filing_date` (newest filing first), or the explicit `sort` string.","example":"relevance"},"complete":{"type":"boolean","description":"False only when the search hit its time limit or lost a shard and the request set allow_partial; the page may then be missing matches. Without allow_partial such a search returns 503.","example":true},"incomplete_reason":{"type":"string","enum":["timeout","shard_failure"],"description":"Why `complete` is false. Omitted when complete.","example":"timeout"},"identifier":{"type":"object","properties":{"office":{"type":["string","null"],"description":"WIPO ST.3 code when q names or implies one office; null for a bare number.","example":"US"},"kind":{"type":"string","enum":["application","registration","ir","signa_id","number"],"example":"number"},"number":{"type":"string","description":"The number in the office's stored form (a tm_ id for signa_id).","example":"1939139"}},"required":["office","kind","number"],"description":"Present when q was read as a trademark number: those records are looked up besides the ranked text match and listed first."},"deprecations":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string","example":"strategies"},"replacement":{"type":"string","example":"similarity"},"sunset":{"type":"string","description":"Date (UTC) from which the deprecated parameter is rejected.","example":"2026-12-28"}},"required":["param","replacement","sunset"]},"description":"The deprecated parameters this request used, each with its replacement. Omitted when none."},"international_registrations":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation actually served. grouped = one row per mark/IR, coverage block present on IR rows; expanded = one row per Madrid designation. A trademark number in q is served expanded: one row per record it names.","example":"grouped"},"index_generation":{"type":["integer","null"],"description":"Generation of the search index that served this response (the grouped or the record index). Cursors are bound to it: after an index rebuild, a cursor from the previous generation returns 400 `cursor_invalid`; restart pagination. null when the generation could not be read (cursors then skip the check).","example":4},"territory_match":{"type":"string","enum":["protection","direct"],"description":"The jurisdictions match mode actually applied. protection (default) expands jurisdictions to protection scope (a EUTM matches a jurisdictions=FR request); direct matches literal territory legs only.","example":"protection"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable warning code for client handling: `<channel>_skipped` (a requested similarity channel produced no clauses for this query; see `channel`), `partial_opposition_coverage` / `partial_seniority_coverage` / `partial_owner_country_coverage` (filter coverage), `expanded_fallback` (a grouped request was served one row per record because the grouped view cannot serve a filter, sort or option; see `affected_filters` / `affected_option`), `identifier_lookup` (`q` is a trademark number, so the response lists the records it names, one row per record), `result_window_reached` (more than 10,000 rows match and this page is the last one the 10,000-row result window lets a relevance or sorted walk reach), `mixed_script` (a mark_text operator value mixes Latin with Greek or Cyrillic letters, which the operators compare as written; see `affected_filter`), `all_words_required` (a q of several words returned fewer than 5 rows in all; q generally requires its words to appear in the mark, so send q as a ranked list of shorter phrases to widen the search), `multi_word_retry_skipped` (the second search allowing a one-letter difference per word was skipped for time).","example":"phonetic_skipped"},"message":{"type":"string","description":"Human-readable explanation of the warning.","example":"phonetic_skipped: the phonetic similarity channel produced no clauses for this query."},"channel":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"],"description":"For `<channel>_skipped` warnings, the requested similarity channel that produced no clauses.","example":"phonetic"},"severity":{"type":"string","enum":["info","warning"],"description":"Warning severity (filter-coverage warnings).","example":"warning"},"affected_filter":{"type":"string","description":"Filter whose behavior is qualified by this warning.","example":"seniority_claims"},"affected_offices":{"type":"array","items":{"type":"string"},"description":"Office codes affected by the coverage or behavior caveat (WIPO ST.3, e.g. US, EM, WO).","example":["EM"]},"affected_filters":{"type":"array","items":{"type":"string"},"description":"For `expanded_fallback` warnings, the filter(s) the grouped view could not serve. Two entries mean the pair could hold on different designations of one mark.","example":["filing_date","status_primary"]},"affected_option":{"type":"string","description":"For `expanded_fallback` warnings, the option the grouped view could not serve: `sort`, `aggregations`, `aggregations_only` or `include_timing`.","example":"sort"},"behavior":{"type":"string","description":"Human-readable explanation of how the API behaves for the affected filter.","example":"Seniority claims are currently indexed from EUIPO only with low coverage; non-EUIPO records may appear as none or unknown."}},"required":["code","message"]},"description":"Coded search warnings: per-channel skip warnings (a REQUESTED similarity channel produced zero clauses for the query shape — e.g. similarity=phonetic on a query too short/high-collision), filter-coverage warnings (an applied filter, e.g. opposition_status, seniority_claims or owner_country, has partial index coverage), `expanded_fallback` (a grouped request was served one row per record), `identifier_lookup` (q is a trademark number, served one row per record it names), `result_window_reached` (the 10,000-row result window, not the data, ends this walk), `all_words_required` (a q of several words returned fewer than 5 rows in all; q generally requires its words to appear in the mark, so send q as a ranked list of shorter phrases to widen the search) and `multi_word_retry_skipped` (the second search allowing a one-letter difference per word was skipped for time). Omitted when there is nothing to warn about."},"execution_time_ms":{"type":"number","example":142},"timing":{"type":"object","properties":{"opensearch_ms":{"type":"number"},"serialization_ms":{"type":"number"},"overhead_ms":{"type":"number"}},"required":["opensearch_ms","serialization_ms","overhead_ms"],"description":"Per-phase timing breakdown (ms). Present only when options.include_timing=true."}},"required":["search_id","query","similarity_applied","ranking_version","order","complete","international_registrations","index_generation","territory_match","execution_time_ms"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"AttorneyClient":{"type":"object","properties":{"id":{"type":"string","example":"own_abc"},"object":{"type":"string","enum":["owner"]},"name":{"type":"string","example":"Signa Technologies Inc."},"canonical_name":{"type":"string","example":"SIGNA TECHNOLOGIES INC."},"country_code":{"type":["string","null"],"example":"US"},"legal_form":{"type":["string","null"],"description":"The kind of legal person, normalised from the office's entity-type code; null when the office states none.","example":"corporation"},"shared_trademark_count":{"type":"integer","description":"Trademarks where this attorney represents this owner (intersection count)","example":12}},"required":["id","object","name","canonical_name","country_code","legal_form","shared_trademark_count"]},"AttorneyClientsResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AttorneyClient"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"FirmIncludedAttorney":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["attorney"]},"name":{"type":"string"},"canonical_name":{"type":"string"},"firm_name":{"type":["string","null"],"description":"The name of this firm (the listing is per firm)."},"country_code":{"type":["string","null"]},"trademark_count":{"type":"integer","description":"Distinct marks this attorney filed naming this firm, in served offices."}},"required":["id","object","name","canonical_name","firm_name","country_code","trademark_count"]},"Firm":{"type":"object","properties":{"id":{"type":"string","example":"firm_a1b2c3d4"},"object":{"type":"string","enum":["firm"]},"name":{"type":"string","description":"Display name of the firm.","example":"Smith & Associates LLP"},"canonical_name":{"type":"string","example":"SMITH & ASSOCIATES LLP"},"country_code":{"type":["string","null"]},"attorney_count":{"type":"integer","description":"Distinct attorneys on the current filings that name this firm, in served offices."},"trademark_count":{"type":"integer","description":"Distinct marks (mark grain): a Madrid IR and its designations count once, matching the default grouped trademark listings. 0 when stats are not yet computed."},"active_count":{"type":"integer","description":"Distinct marks (mark grain) that are registered or still in prosecution. Always present; 0 when stats are not yet computed.","example":300},"registration_rate":{"type":["number","null"],"description":"Deprecated: use grant_rate — same value; registration_rate is a misnomer.","deprecated":true},"grant_rate":{"type":["number","null"],"description":"Share of concluded prosecutions that were ever granted. Same value as the deprecated registration_rate."},"latest_filing_date":{"type":["string","null"]},"stats_computed_at":{"type":["string","null"],"description":"When the firm's aggregate stats (attorney_count, trademark_count, active_count, grant_rate, latest_filing_date) were last recomputed. null when never computed."},"aliases":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"source_office_code":{"type":["string","null"],"description":"WIPO ST.3 code of the office that recorded this alias."}},"required":["name","type","source_office_code"]}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attorneys":{"type":"array","items":{"$ref":"#/components/schemas/FirmIncludedAttorney"},"description":"With `include=attorneys`: up to 20 attorneys whose current filings name this firm, most trademarks first. The full list is `GET /v1/firms/{id}/attorneys`."},"attorneys_has_more":{"type":"boolean","description":"With `include=attorneys`: true when more attorneys than the 20 listed name this firm."}},"required":["id","object","name","canonical_name","country_code","attorney_count","trademark_count","active_count","registration_rate","grant_rate","latest_filing_date","stats_computed_at","aliases","created_at","updated_at"]},"FirmResponse":{"allOf":[{"$ref":"#/components/schemas/Firm"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"FirmSummary":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["firm"]},"name":{"type":"string"},"canonical_name":{"type":"string"},"country_code":{"type":["string","null"]},"attorney_count":{"type":"integer","description":"Distinct attorneys on the current filings that name this firm, in served offices."},"trademark_count":{"type":"integer","description":"Distinct marks (mark grain): a Madrid IR and its designations count once, matching the default grouped trademark listings. 0 when stats are not yet computed."},"active_count":{"type":"integer","description":"Distinct marks (mark grain) that are registered or still in prosecution. Always present; 0 when stats are not yet computed."},"registration_rate":{"type":["number","null"],"description":"Deprecated: use grant_rate — same value; registration_rate is a misnomer.","deprecated":true},"grant_rate":{"type":["number","null"],"description":"Share of concluded prosecutions that were ever granted. Same value as the deprecated registration_rate."},"latest_filing_date":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","object","name","canonical_name","country_code","attorney_count","trademark_count","active_count","registration_rate","grant_rate","latest_filing_date","created_at"]},"FirmListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/FirmSummary"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"FirmAttorneyItem":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["attorney"]},"name":{"type":"string"},"canonical_name":{"type":"string"},"firm_name":{"type":["string","null"],"description":"The name of this firm (the listing is per firm)."},"country_code":{"type":["string","null"]},"trademark_count":{"type":"integer","description":"Distinct marks (mark grain) this attorney filed naming this firm, in served offices: a Madrid IR and its designations count once. Not the attorney's total."},"registration_rate":{"type":["number","null"],"description":"Deprecated: use grant_rate — same value; registration_rate is a misnomer.","deprecated":true},"grant_rate":{"type":["number","null"],"description":"Share of concluded prosecutions that were ever granted, over the filings naming this firm. Same value as the deprecated registration_rate."},"latest_filing_date":{"type":["string","null"],"description":"Latest filing date among the filings naming this firm."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","canonical_name","firm_name","country_code","trademark_count","registration_rate","grant_rate","latest_filing_date","created_at","updated_at"]},"FirmAttorneyListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/FirmAttorneyItem"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"FirmTrademarksV1Response":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkSummaryV1"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"search_meta":{"type":"object","properties":{"search_id":{"type":"string","example":"srch_abc123"},"query":{"type":["string","null"],"description":"Echo of the text query, or null for filter-only searches and for a q list.","example":"SIGNA"},"similarity_applied":{"type":"array","items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"The similarity channels q ran on (identical is always included). Empty without q.","example":["identical","fuzzy","embedded","lookalike"]},"ranking_version":{"type":"string","description":"Version of the ranking that ordered this response. Cursors are bound to it: a new version restarts pagination (400 `cursor_invalid`).","example":"v13"},"order":{"type":"string","description":"The order applied: `relevance` (q present), `mark_text_fit` (text order for a mark_text-only request), `filing_date` (newest filing first), or the explicit `sort` string.","example":"relevance"},"complete":{"type":"boolean","description":"False only when the search hit its time limit or lost a shard and the request set allow_partial; the page may then be missing matches. Without allow_partial such a search returns 503.","example":true},"incomplete_reason":{"type":"string","enum":["timeout","shard_failure"],"description":"Why `complete` is false. Omitted when complete.","example":"timeout"},"identifier":{"type":"object","properties":{"office":{"type":["string","null"],"description":"WIPO ST.3 code when q names or implies one office; null for a bare number.","example":"US"},"kind":{"type":"string","enum":["application","registration","ir","signa_id","number"],"example":"number"},"number":{"type":"string","description":"The number in the office's stored form (a tm_ id for signa_id).","example":"1939139"}},"required":["office","kind","number"],"description":"Present when q was read as a trademark number: those records are looked up besides the ranked text match and listed first."},"deprecations":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string","example":"strategies"},"replacement":{"type":"string","example":"similarity"},"sunset":{"type":"string","description":"Date (UTC) from which the deprecated parameter is rejected.","example":"2026-12-28"}},"required":["param","replacement","sunset"]},"description":"The deprecated parameters this request used, each with its replacement. Omitted when none."},"international_registrations":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation actually served. grouped = one row per mark/IR, coverage block present on IR rows; expanded = one row per Madrid designation. A trademark number in q is served expanded: one row per record it names.","example":"grouped"},"index_generation":{"type":["integer","null"],"description":"Generation of the search index that served this response (the grouped or the record index). Cursors are bound to it: after an index rebuild, a cursor from the previous generation returns 400 `cursor_invalid`; restart pagination. null when the generation could not be read (cursors then skip the check).","example":4},"territory_match":{"type":"string","enum":["protection","direct"],"description":"The jurisdictions match mode actually applied. protection (default) expands jurisdictions to protection scope (a EUTM matches a jurisdictions=FR request); direct matches literal territory legs only.","example":"protection"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable warning code for client handling: `<channel>_skipped` (a requested similarity channel produced no clauses for this query; see `channel`), `partial_opposition_coverage` / `partial_seniority_coverage` / `partial_owner_country_coverage` (filter coverage), `expanded_fallback` (a grouped request was served one row per record because the grouped view cannot serve a filter, sort or option; see `affected_filters` / `affected_option`), `identifier_lookup` (`q` is a trademark number, so the response lists the records it names, one row per record), `result_window_reached` (more than 10,000 rows match and this page is the last one the 10,000-row result window lets a relevance or sorted walk reach), `mixed_script` (a mark_text operator value mixes Latin with Greek or Cyrillic letters, which the operators compare as written; see `affected_filter`), `all_words_required` (a q of several words returned fewer than 5 rows in all; q generally requires its words to appear in the mark, so send q as a ranked list of shorter phrases to widen the search), `multi_word_retry_skipped` (the second search allowing a one-letter difference per word was skipped for time).","example":"phonetic_skipped"},"message":{"type":"string","description":"Human-readable explanation of the warning.","example":"phonetic_skipped: the phonetic similarity channel produced no clauses for this query."},"channel":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"],"description":"For `<channel>_skipped` warnings, the requested similarity channel that produced no clauses.","example":"phonetic"},"severity":{"type":"string","enum":["info","warning"],"description":"Warning severity (filter-coverage warnings).","example":"warning"},"affected_filter":{"type":"string","description":"Filter whose behavior is qualified by this warning.","example":"seniority_claims"},"affected_offices":{"type":"array","items":{"type":"string"},"description":"Office codes affected by the coverage or behavior caveat (WIPO ST.3, e.g. US, EM, WO).","example":["EM"]},"affected_filters":{"type":"array","items":{"type":"string"},"description":"For `expanded_fallback` warnings, the filter(s) the grouped view could not serve. Two entries mean the pair could hold on different designations of one mark.","example":["filing_date","status_primary"]},"affected_option":{"type":"string","description":"For `expanded_fallback` warnings, the option the grouped view could not serve: `sort`, `aggregations`, `aggregations_only` or `include_timing`.","example":"sort"},"behavior":{"type":"string","description":"Human-readable explanation of how the API behaves for the affected filter.","example":"Seniority claims are currently indexed from EUIPO only with low coverage; non-EUIPO records may appear as none or unknown."}},"required":["code","message"]},"description":"Coded search warnings: per-channel skip warnings (a REQUESTED similarity channel produced zero clauses for the query shape — e.g. similarity=phonetic on a query too short/high-collision), filter-coverage warnings (an applied filter, e.g. opposition_status, seniority_claims or owner_country, has partial index coverage), `expanded_fallback` (a grouped request was served one row per record), `identifier_lookup` (q is a trademark number, served one row per record it names), `result_window_reached` (the 10,000-row result window, not the data, ends this walk), `all_words_required` (a q of several words returned fewer than 5 rows in all; q generally requires its words to appear in the mark, so send q as a ranked list of shorter phrases to widen the search) and `multi_word_retry_skipped` (the second search allowing a one-letter difference per word was skipped for time). Omitted when there is nothing to warn about."},"execution_time_ms":{"type":"number","example":142},"timing":{"type":"object","properties":{"opensearch_ms":{"type":"number"},"serialization_ms":{"type":"number"},"overhead_ms":{"type":"number"}},"required":["opensearch_ms","serialization_ms","overhead_ms"],"description":"Per-phase timing breakdown (ms). Present only when options.include_timing=true."}},"required":["search_id","query","similarity_applied","ranking_version","order","complete","international_registrations","index_generation","territory_match","execution_time_ms"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"EntityListedAncestor":{"type":["object","null"],"properties":{"id":{"type":"string","description":"The listed ancestor entity id.","example":"ent_019eb3c8"},"object":{"type":"string","enum":["entity"]},"name":{"type":"string","example":"NIKE, Inc."},"ticker":{"type":["string","null"],"description":"The listed ancestor's own ticker.","example":"NKE"}},"required":["id","object","name","ticker"],"description":"The listed ancestor (the nearest listed company up the GLEIF direct-parent chain, else the GLEIF ultimate parent), when it resolves to a live entity in our system. null for a directly-listed entity, or when the ancestor exists only in the GLEIF graph. Ultimate-parent inheritance takes effect after the weekly GLEIF refresh."},"EntityListing":{"type":"object","properties":{"status":{"type":"string","enum":["listed","subsidiary_of_listed"],"description":"'listed' = the entity is itself publicly listed; 'subsidiary_of_listed' = it inherits a ticker from a listed ancestor.","example":"subsidiary_of_listed"},"ticker":{"type":["string","null"],"description":"The entity's own ticker (listed) or the inherited ancestor ticker (subsidiary_of_listed).","example":"NKE"},"exch_code":{"type":["string","null"],"description":"Exchange / market code (display only).","example":"XNYS"},"lei":{"type":["string","null"],"description":"LEI of the listed company: the entity's own LEI when listed, else the listed ancestor's LEI.","example":"INR2EJN1ERAN0W5ZP974"},"source":{"type":"string","enum":["direct","inherited"],"description":"Derived from status: 'listed' → 'direct', 'subsidiary_of_listed' → 'inherited'.","example":"inherited"},"listed_ancestor":{"$ref":"#/components/schemas/EntityListedAncestor"}},"required":["status","ticker","exch_code","lei","source","listed_ancestor"],"description":"Public-listing decoration (ENG-117). Present only when the entity is listed or a subsidiary of a listed company; OMITTED otherwise (absence ≠ confirmed-private)."},"EntityMemberLink":{"type":"object","properties":{"method":{"type":"string","enum":["international_registration","shared_identifier","public_company","portfolio_overlap","manual_review","other"],"description":"How this member was linked into the entity. `international_registration` = shared Madrid IR number; `shared_identifier` = shared office identifier; `public_company` = linked via shared public-company records; `portfolio_overlap` = portfolio-overlap heuristic; `manual_review` = confirmed by curation/review.","example":"international_registration"},"match_strength":{"type":["string","null"],"enum":["high","medium","low",null],"description":"Coarse confidence band for the link. null when not scored.","example":"high"},"reviewed":{"type":"boolean","description":"Whether the link was confirmed by adjudication/manual review (vs a purely automated match).","example":false},"matched_irs":{"type":"array","items":{"type":"string"},"description":"Matched canonical IR numbers (international_registration).","example":["1600856","1617880"]},"matched_identifiers":{"type":"array","items":{"type":"string"},"description":"Matched office-identifier values (shared_identifier)."}},"required":["method","match_strength","reviewed"],"description":"How a member owner was linked into the entity."},"EntityMember":{"type":"object","properties":{"id":{"type":"string","example":"own_a1b2c3d4"},"object":{"type":"string","enum":["owner"]},"name":{"type":"string","example":"8x8, Inc."},"canonical_name":{"type":"string","example":"8X8"},"country_code":{"type":["string","null"],"example":"US"},"legal_form":{"type":["string","null"],"description":"The kind of legal person, normalised from the office's entity-type code; null when the office states none.","example":"corporation"},"office_code":{"type":["string","null"],"description":"The per-office cluster this member owner came from (WIPO ST.3 uppercase).","example":"US"},"link":{"$ref":"#/components/schemas/EntityMemberLink"}},"required":["id","object","name","canonical_name","country_code","legal_form","office_code","link"]},"Entity":{"type":"object","properties":{"id":{"type":"string","example":"ent_019eb3c8"},"object":{"type":"string","enum":["entity"]},"name":{"type":"string","description":"Survivorship display name.","example":"8x8, Inc."},"country_code":{"type":["string","null"],"example":"US"},"legal_form":{"type":["string","null"],"description":"The kind of legal person, normalised from the member owners' office entity-type codes; null when none is stated.","example":"corporation"},"publicly_traded":{"type":"boolean","description":"Any active SEC company with a ticker across members, OR the entity itself is listed / a subsidiary of a listed company (ENG-117)."},"ticker":{"type":["string","null"],"description":"Survivorship ticker (first of `tickers`). null when none.","example":"EGHT"},"tickers":{"type":"array","items":{"type":"string"},"description":"Deduped uppercased tickers: member-company SEC tickers UNION the entity's own direct/inherited (subsidiary_of_listed) listing_ticker (ENG-117) — so this includes inherited subsidiary tickers; direct-vs-inherited provenance is in the `listing` block.","example":["EGHT"]},"lei":{"type":["string","null"],"description":"Survivorship LEI, uppercased: the entity's own LEI when set, else the first GLEIF LEI across member companies. null when none.","example":"HWUPKR0MPOU8FGXBT394"},"has_lei":{"type":"boolean","description":"Whether the entity has an LEI: its own, or any GLEIF LEI across member companies."},"trademark_count":{"type":["integer","null"],"description":"COUNT(DISTINCT trademark) across all member owners (co-owned marks counted once). `null` when the count could not be computed within the read-path timeout for a very large entity (fail-open — the rest of the detail is still served)."},"active_count":{"type":["integer","null"],"description":"COUNT(DISTINCT active trademark) (registered + pending stages) across all member owners. Computed live at request time from the same source as trademark_count, so active_count <= trademark_count. `null` on the same read-path-timeout fail-open as trademark_count."},"member_count":{"type":"integer","example":5},"parent_entity_id":{"type":["string","null"],"description":"GLEIF Level 2 parent. null when none.","example":"ent_…"},"listing":{"$ref":"#/components/schemas/EntityListing"},"members":{"type":"array","items":{"$ref":"#/components/schemas/EntityMember"},"description":"Member owners + per-link evidence."},"updated_at":{"type":["string","null"]}},"required":["id","object","name","country_code","legal_form","publicly_traded","ticker","tickers","lei","has_lei","trademark_count","active_count","member_count","parent_entity_id","members","updated_at"]},"EntityResponse":{"allOf":[{"$ref":"#/components/schemas/Entity"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"EntitySummary":{"type":"object","properties":{"id":{"type":"string","example":"ent_019eb3c8"},"object":{"type":"string","enum":["entity"]},"name":{"type":"string","example":"8x8, Inc."},"country_code":{"type":["string","null"],"example":"US"},"legal_form":{"type":["string","null"],"description":"The kind of legal person, normalised from the member owners' office entity-type codes; null when none is stated.","example":"corporation"},"publicly_traded":{"type":"boolean"},"ticker":{"type":["string","null"]},"lei":{"type":["string","null"]},"trademark_count":{"type":"integer"},"active_count":{"type":"integer","description":"COUNT(DISTINCT active trademark) (registered + pending) across member owners."},"member_count":{"type":"integer"}},"required":["id","object","name","country_code","legal_form","publicly_traded","ticker","lei","trademark_count","active_count","member_count"]},"EntityListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EntitySummary"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"EntityTrademarksV1Response":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkSummaryV1"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"search_meta":{"type":"object","properties":{"search_id":{"type":"string","example":"srch_abc123"},"query":{"type":["string","null"],"description":"Echo of the text query, or null for filter-only searches and for a q list.","example":"SIGNA"},"similarity_applied":{"type":"array","items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"The similarity channels q ran on (identical is always included). Empty without q.","example":["identical","fuzzy","embedded","lookalike"]},"ranking_version":{"type":"string","description":"Version of the ranking that ordered this response. Cursors are bound to it: a new version restarts pagination (400 `cursor_invalid`).","example":"v13"},"order":{"type":"string","description":"The order applied: `relevance` (q present), `mark_text_fit` (text order for a mark_text-only request), `filing_date` (newest filing first), or the explicit `sort` string.","example":"relevance"},"complete":{"type":"boolean","description":"False only when the search hit its time limit or lost a shard and the request set allow_partial; the page may then be missing matches. Without allow_partial such a search returns 503.","example":true},"incomplete_reason":{"type":"string","enum":["timeout","shard_failure"],"description":"Why `complete` is false. Omitted when complete.","example":"timeout"},"identifier":{"type":"object","properties":{"office":{"type":["string","null"],"description":"WIPO ST.3 code when q names or implies one office; null for a bare number.","example":"US"},"kind":{"type":"string","enum":["application","registration","ir","signa_id","number"],"example":"number"},"number":{"type":"string","description":"The number in the office's stored form (a tm_ id for signa_id).","example":"1939139"}},"required":["office","kind","number"],"description":"Present when q was read as a trademark number: those records are looked up besides the ranked text match and listed first."},"deprecations":{"type":"array","items":{"type":"object","properties":{"param":{"type":"string","example":"strategies"},"replacement":{"type":"string","example":"similarity"},"sunset":{"type":"string","description":"Date (UTC) from which the deprecated parameter is rejected.","example":"2026-12-28"}},"required":["param","replacement","sunset"]},"description":"The deprecated parameters this request used, each with its replacement. Omitted when none."},"international_registrations":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation actually served. grouped = one row per mark/IR, coverage block present on IR rows; expanded = one row per Madrid designation. A trademark number in q is served expanded: one row per record it names.","example":"grouped"},"index_generation":{"type":["integer","null"],"description":"Generation of the search index that served this response (the grouped or the record index). Cursors are bound to it: after an index rebuild, a cursor from the previous generation returns 400 `cursor_invalid`; restart pagination. null when the generation could not be read (cursors then skip the check).","example":4},"territory_match":{"type":"string","enum":["protection","direct"],"description":"The jurisdictions match mode actually applied. protection (default) expands jurisdictions to protection scope (a EUTM matches a jurisdictions=FR request); direct matches literal territory legs only.","example":"protection"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable warning code for client handling: `<channel>_skipped` (a requested similarity channel produced no clauses for this query; see `channel`), `partial_opposition_coverage` / `partial_seniority_coverage` / `partial_owner_country_coverage` (filter coverage), `expanded_fallback` (a grouped request was served one row per record because the grouped view cannot serve a filter, sort or option; see `affected_filters` / `affected_option`), `identifier_lookup` (`q` is a trademark number, so the response lists the records it names, one row per record), `result_window_reached` (more than 10,000 rows match and this page is the last one the 10,000-row result window lets a relevance or sorted walk reach), `mixed_script` (a mark_text operator value mixes Latin with Greek or Cyrillic letters, which the operators compare as written; see `affected_filter`), `all_words_required` (a q of several words returned fewer than 5 rows in all; q generally requires its words to appear in the mark, so send q as a ranked list of shorter phrases to widen the search), `multi_word_retry_skipped` (the second search allowing a one-letter difference per word was skipped for time).","example":"phonetic_skipped"},"message":{"type":"string","description":"Human-readable explanation of the warning.","example":"phonetic_skipped: the phonetic similarity channel produced no clauses for this query."},"channel":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"],"description":"For `<channel>_skipped` warnings, the requested similarity channel that produced no clauses.","example":"phonetic"},"severity":{"type":"string","enum":["info","warning"],"description":"Warning severity (filter-coverage warnings).","example":"warning"},"affected_filter":{"type":"string","description":"Filter whose behavior is qualified by this warning.","example":"seniority_claims"},"affected_offices":{"type":"array","items":{"type":"string"},"description":"Office codes affected by the coverage or behavior caveat (WIPO ST.3, e.g. US, EM, WO).","example":["EM"]},"affected_filters":{"type":"array","items":{"type":"string"},"description":"For `expanded_fallback` warnings, the filter(s) the grouped view could not serve. Two entries mean the pair could hold on different designations of one mark.","example":["filing_date","status_primary"]},"affected_option":{"type":"string","description":"For `expanded_fallback` warnings, the option the grouped view could not serve: `sort`, `aggregations`, `aggregations_only` or `include_timing`.","example":"sort"},"behavior":{"type":"string","description":"Human-readable explanation of how the API behaves for the affected filter.","example":"Seniority claims are currently indexed from EUIPO only with low coverage; non-EUIPO records may appear as none or unknown."}},"required":["code","message"]},"description":"Coded search warnings: per-channel skip warnings (a REQUESTED similarity channel produced zero clauses for the query shape — e.g. similarity=phonetic on a query too short/high-collision), filter-coverage warnings (an applied filter, e.g. opposition_status, seniority_claims or owner_country, has partial index coverage), `expanded_fallback` (a grouped request was served one row per record), `identifier_lookup` (q is a trademark number, served one row per record it names), `result_window_reached` (the 10,000-row result window, not the data, ends this walk), `all_words_required` (a q of several words returned fewer than 5 rows in all; q generally requires its words to appear in the mark, so send q as a ranked list of shorter phrases to widen the search) and `multi_word_retry_skipped` (the second search allowing a one-letter difference per word was skipped for time). Omitted when there is nothing to warn about."},"execution_time_ms":{"type":"number","example":142},"timing":{"type":"object","properties":{"opensearch_ms":{"type":"number"},"serialization_ms":{"type":"number"},"overhead_ms":{"type":"number"}},"required":["opensearch_ms","serialization_ms","overhead_ms"],"description":"Per-phase timing breakdown (ms). Present only when options.include_timing=true."}},"required":["search_id","query","similarity_applied","ranking_version","order","complete","international_registrations","index_generation","territory_match","execution_time_ms"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"EntityFamilyNode":{"type":["object","null"],"properties":{"id":{"type":"string","example":"ent_…"},"object":{"type":"string","enum":["entity"]},"name":{"type":"string"},"country_code":{"type":["string","null"]},"relationship":{"type":"string","enum":["parent","direct_subsidiary"],"example":"direct_subsidiary"},"source":{"type":"string","enum":["gleif"]}},"required":["id","object","name","country_code","relationship","source"],"description":"Direct GLEIF parent, or null."},"EntityFamily":{"type":"object","properties":{"object":{"type":"string","enum":["entity_family"]},"parent":{"$ref":"#/components/schemas/EntityFamilyNode"},"children":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/EntityFamilyNode"},{"type":"object"}]},"description":"Direct GLEIF subsidiaries (1 level)."},"source":{"type":"string","enum":["gleif"]},"coverage_caveat":{"type":"string","description":"GLEIF Level 2 covers LEI-reporting companies only; an absent edge does not imply no relationship."}},"required":["object","parent","children","source","coverage_caveat"]},"EntityFamilyResponse":{"allOf":[{"$ref":"#/components/schemas/EntityFamily"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"Proceeding":{"type":"object","properties":{"id":{"type":"string","example":"prc_a1b2c3d4"},"object":{"type":"string","enum":["proceeding"]},"proceeding_type":{"type":"string","example":"opposition"},"proceeding_number":{"type":["string","null"],"description":"The office's identifier for the proceeding, when it issues one. For CIPO, proceeding_number is the office's per-record sequence identifier (1, 2, …), not a Board docket number.","example":"91234567"},"status":{"type":["string","null"],"example":"decided_rejected"},"outcome":{"type":["string","null"],"enum":["challenger_won","challenger_lost","mixed","settled","withdrawn","default_judgment","pending","other",null],"description":"Normalized proceeding outcome from the challenger perspective.","example":"challenger_won"},"duration_days":{"type":["integer","null"],"description":"Decision date minus filed date in days. Null when either date is missing.","example":219},"office_code":{"type":["string","null"],"example":"US"},"filed_date":{"type":["string","null"],"example":"2024-06-15"},"decision_date":{"type":["string","null"],"example":"2025-01-20"},"contested_classes":{"type":["array","null"],"items":{"type":"integer"}},"decision_outcome":{"type":["string","null"]},"trademark_id":{"type":"string","example":"tm_7d4e1f2a3b8c9d0e"},"trademark_role":{"type":"string","enum":["contested","asserted"],"description":"Which side `trademark_id` is on. `contested`: the mark the proceeding targets (the opposed application, the registration under cancellation, the appealed application). `asserted`: a mark the opposer or petitioner pleaded as a prior right. One proceeding links one row per involved mark; use `trademark_role` to tell the opposed mark from the opposer's marks.","example":"contested"},"description":{"type":["string","null"]},"created_at":{"type":["string","null"],"description":"When Signa first stored this proceeding row."},"updated_at":{"type":["string","null"],"description":"When Signa last changed this proceeding row."}},"required":["id","object","proceeding_type","proceeding_number","status","outcome","duration_days","office_code","filed_date","decision_date","contested_classes","decision_outcome","trademark_id","trademark_role","description","created_at","updated_at"]},"ProceedingListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Proceeding"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"aggregations":{"$ref":"#/components/schemas/Aggregations"},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"ProceedingParty":{"type":"object","properties":{"owner_id":{"type":["string","null"],"example":"own_xyz"},"name":{"type":["string","null"],"example":"Big Corp"},"role":{"type":"string","example":"opponent"},"country_code":{"type":["string","null"],"example":"US"}},"required":["owner_id","name","role","country_code"]},"ProceedingLinkedTrademark":{"type":["object","null"],"properties":{"id":{"type":"string","example":"tm_7d4e1f2a3b8c9d0e"},"object":{"type":"string","enum":["trademark"]},"mark_text":{"type":["string","null"],"example":"ACME"},"application_number":{"type":["string","null"],"description":"The linked mark's office application number.","example":"90123456"},"office_code":{"type":["string","null"],"example":"US"},"trademark_role":{"type":"string","enum":["contested","asserted"],"example":"contested"}},"required":["id","object","mark_text","application_number","office_code","trademark_role"],"description":"The mark this row belongs to (`trademark_id`), with its role."},"ProceedingDetail":{"allOf":[{"$ref":"#/components/schemas/Proceeding"},{"type":"object","properties":{"parties":{"type":"array","items":{"$ref":"#/components/schemas/ProceedingParty"}},"trademark":{"$ref":"#/components/schemas/ProceedingLinkedTrademark"},"trademarks":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ProceedingLinkedTrademark"},{"type":"object"}]},"description":"Every mark linked to this proceeding (same office, type and proceeding number), each with its `trademark_role`. Includes `trademark`. Lets one call show the opposed mark next to the marks the opposer asserted."}},"required":["parties","trademark","trademarks"]}]},"ProceedingResponse":{"allOf":[{"$ref":"#/components/schemas/ProceedingDetail"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"AssignmentListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Assignment"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"AssignmentDetail":{"allOf":[{"$ref":"#/components/schemas/Assignment"},{"type":"object","properties":{"correspondent":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{}},{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}],"example":{"name":"Jane Correspondent"}},"parties":{"type":"array","items":{"$ref":"#/components/schemas/AssignmentParty"}},"properties":{"type":"array","items":{"$ref":"#/components/schemas/AssignmentProperty"}}},"required":["correspondent","parties","properties"]}]},"AssignmentResponse":{"allOf":[{"$ref":"#/components/schemas/AssignmentDetail"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"ComputedDeadline":{"allOf":[{"$ref":"#/components/schemas/DeadlineRow"},{"type":"object","properties":{"effective_from":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Earliest authoritative date for the rule, or null when no boundary is established.","example":null},"last_verified":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date the parent jurisdiction configuration was last verified.","example":"2026-03-10"},"status":{"type":"string","example":"window_open"},"days_until_due":{"type":"integer","example":248},"days_until_grace_expiry":{"type":"integer","example":432},"urgency":{"type":"string","example":"routine"}},"required":["effective_from","last_verified","status","days_until_due","days_until_grace_expiry","urgency"]}]},"DeadlineUnsupportedReason":{"type":["string","null"],"enum":["unsupported_jurisdiction","requires_office_date","holiday_calendar_out_of_coverage","ambiguous_response_linkage","ambiguous_extension_linkage","date_basis_not_accepted","no_rule_for_family","no_rule_for_route","no_rule_for_era","unsupported_office","missing_operative_date","extension_not_available_under_rule","maintenance_window_not_established","ambiguous_stated_deadline_linkage","stated_deadline_not_resolvable","ambiguous_notice_of_allowance_linkage","notice_of_allowance_withdrawn","superseded_by_corrected_notice","stated_deadline_office_mismatch","maintenance_floor_exceeds_absolute_cap",null],"description":"Reason vocabulary for the new prosecution capability and result fields: the two maintenance reasons used by the maintenance support entry plus every prosecution engine reason code."},"DeadlineSupport":{"type":"object","properties":{"type":{"type":"string","enum":["maintenance","oa_response","suspension_inquiry_response","post_registration_oa_response","sou"],"example":"oa_response"},"supported":{"type":"boolean","description":"`false` only when `status` is `unsupported` — i.e. Signa models no rule for this office/route/type and the office stated no date either."},"status":{"type":"string","enum":["computed","stated","facts_required","unsupported"],"description":"What actually happened for this deadline type. `computed`: a modelled rule produced or retired a date. `stated`: no modelled rule exists, but the office stated the date itself (Madrid Rule 17(2)(vii)-(viii) — the Madrid System does not set the holder response period). `facts_required`: a rule exists but nothing triggered it; supply the trigger facts. EUIPO is the standing example — its rules are verified, but Signa stores no EUIPO examination events, so the trigger is always caller-supplied. `unsupported`: no rule exists at all.","example":"facts_required"},"reason":{"$ref":"#/components/schemas/DeadlineUnsupportedReason"},"rule_ids":{"type":"array","items":{"type":"string"},"description":"The modelled rules behind this deadline type. Populated for prosecution types (empty when none are modelled) and omitted for `maintenance`, whose rules are not slug-identified in this vocabulary.","example":["uspto_domestic_oa_response@2022-12-03"]}},"required":["type","supported","status","reason"]},"ProsecutionRuleIdentity":{"type":["object","null"],"properties":{"rule_id":{"type":"string","example":"uspto_domestic_oa_response@2022-12-03"},"authority_level":{"type":"string","enum":["statute","regulation","office_practice","office_notice"]},"effective_from":{"type":"string","example":"2022-12-03"},"effective_until":{"type":["string","null"],"description":"INCLUSIVE last day the regime was in force; null while still in force.","example":null},"applicability_basis":{"type":"string","enum":["office_action_issue_date","notice_of_allowance_issue_date","time_limit_set_date","notification_date","application_filing_date","registration_date","proceeding_institution_date"],"description":"WHICH date on the case selected this era. Not the same as `effective_from`, which says when the regime began."},"last_verified":{"type":"string","example":"2026-08-31"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ProsecutionRuleSource"}}},"required":["rule_id","authority_level","effective_from","effective_until","applicability_basis","last_verified","sources"],"description":"The rule that produced the date, with its sources. Non-null for every computed or closed deadline (the §11.8 guardrail: a computed date that cannot cite its rule does not ship). Null only for `stated` outcomes, which cite `stated_by_fact_id`/`stated_basis` instead, and for declines made before a rule was selected."},"ProsecutionDeadline":{"type":"object","properties":{"object":{"type":"string","enum":["prosecution_deadline"]},"outcome":{"type":"string","enum":["computed","closed","stated","not_applicable","insufficient_facts","ambiguous","unsupported_jurisdiction"],"example":"computed"},"deadline_type":{"type":["string","null"],"enum":["oa_response","suspension_inquiry_response","post_registration_oa_response","sou",null],"description":"Null when no rule was selected (or the date was office-stated)."},"trigger_fact_id":{"type":"string","description":"The `facts[].id` whose date started this clock.","example":"oa-1"},"trigger_date":{"type":["string","null"],"example":"2024-02-01"},"trigger_date_basis":{"type":["string","null"],"enum":["mailed_row","ib_transmittal_row","written_row","caller_supplied",null]},"linkage_quality":{"type":["string","null"],"enum":["explicit","inferred","ambiguous",null]},"low_confidence":{"type":"boolean"},"due_date":{"type":["string","null"],"example":"2024-05-01"},"extended_due_date":{"type":["string","null"]},"effective_due_date":{"type":["string","null"],"description":"The date to act on: `extended_due_date ?? due_date`, raised to any statutory floor."},"due_date_adjustment":{"type":["string","null"],"enum":["moved","unchanged","not_checked","month_end_overflow",null],"description":"What the business-day roll did to this row: `moved` (the roll ran and changed the date), `unchanged` (the roll ran and the date was already an open day), `not_checked` (no pinned closure list verified the date), `month_end_overflow` (the period ran into the following calendar month because its end day number does not exist in the target one; this reason subsumes any business-day roll applied afterwards). `not_checked` covers a rule with no roll rule (the date is the raw statutory arithmetic), a date outside the office calendar's pinned coverage (the deterministic weekend and fixed-holiday roll may still have been applied), and an office-stated date, which is published exactly as the office stated it. The true deadline can only be the same as a `not_checked` date or LATER, never earlier. Null exactly when no date was produced. Exactly the maintenance `due_date_adjustment` vocabulary: the two fields are the same published enum, so a value the engine adds on one side is never silently invalid on the other. The prosecution engine emits only three of the four today (`moved`, `unchanged`, `not_checked`); `month_end_overflow` is produced by a maintenance rule (Mexico) that has no prosecution counterpart, and the enum stays wide on purpose so the two fields never drift apart.","example":"moved"},"base_source":{"type":["string","null"],"enum":["rule_period","stated_deadline","rule_absolute_cap",null],"description":"Where the unextended deadline came from."},"rejected_stated_due_date":{"type":["string","null"],"description":"A stated due date the engine REJECTED for exceeding the rule's absolute cap, kept as structured provenance."},"closed_by_fact_id":{"type":["string","null"],"description":"The fact that retired this deadline. Null when nothing retired it, and on a closed `post_registration_oa_response` row, whose closing entry (named in `notes`) is not one of the record's facts."},"closed_by":{"type":["string","null"],"enum":["response","abandonment","sou","acceptance",null],"description":"What retired this deadline. `acceptance` (only on `post_registration_oa_response`): the office accepted the filing the post-registration action examined, so no response is due."},"stated_by_fact_id":{"type":["string","null"],"description":"For `outcome: \"stated\"`: the `stated_deadline` fact that carried the date."},"stated_basis":{"type":["string","null"],"enum":["office_issue_date","office_to_ib_send_date","ib_to_holder_transmittal_date","holder_receipt_date","explicit_dates",null],"description":"The declared calculation basis (Madrid Rule 17(2)(viii))."},"reason":{"allOf":[{"$ref":"#/components/schemas/DeadlineUnsupportedReason"},{"description":"Non-null exactly when the outcome produced no date."}]},"notes":{"type":"array","items":{"type":"string"}},"rule":{"$ref":"#/components/schemas/ProsecutionRuleIdentity"}},"required":["object","outcome","deadline_type","trigger_fact_id","trigger_date","trigger_date_basis","linkage_quality","low_confidence","due_date","extended_due_date","effective_due_date","due_date_adjustment","base_source","rejected_stated_due_date","closed_by_fact_id","closed_by","stated_by_fact_id","stated_basis","reason","notes","rule"]},"DeadlineComputation":{"type":"object","properties":{"object":{"type":"string","enum":["deadline_computation"]},"jurisdiction_code":{"type":"string","example":"US"},"filing_route":{"type":"string","enum":["national","regional","madrid"],"example":"national"},"supported":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["unsupported_jurisdiction","requires_office_date",null],"description":"Why no MAINTENANCE schedule was computed; null when `supported` is true. `unsupported_jurisdiction`: no rules are modeled for the jurisdiction. `requires_office_date`: the record does not carry the input the statute needs (Australian direct marks filed before 1996-01-01, Singapore direct marks filed before 1999-01-15, a Madrid designation with no international-registration date, or a Swedish, Icelandic, Norwegian or Finnish direct filing made before the renewal-anchor reform of its office (SE 2019-01-01, IS 2020-09-01, NO 2010-07-01, FI 2019-05-01) with no `registration_date`, since the old-regime term runs from registration, or a record where every rule it owes lacks the date it runs from (for example a registered or expired mark with no registration date where the rules run from registration, or a Swedish mark registered on or after 2019-01-01 with no filing date; a cancelled national mark owes only a renewal that opens a modelled restoration window, as in Japan, so elsewhere (and on a Madrid designation, which has no restoration window) it is supported with no deadlines, unless `include_missed` asks for its missed rows too, which it then owes)) and no `expiry_date` was supplied to anchor on; supply the office-stated `expiry_date` and the schedule is computed from it. The engine declines to guess. In a jurisdiction with modeled rules, never `requires_office_date` for a mark whose status ends every obligation (abandoned, withdrawn, surrendered, invalidated, or refused other than a WIPO international registration record, which keeps its renewal): it is supported with no deadlines."},"deadlines":{"type":"array","items":{"$ref":"#/components/schemas/ComputedDeadline"}},"unsupported_rules":{"type":"array","items":{"$ref":"#/components/schemas/UnsupportedDeadlineRule"},"description":"Rules that apply to this mark but were declined because it lacks the date the statute anchors them on. `deadlines` has no row for them, so without this list the obligation would be silently absent. Always present: `[]` when nothing was declined, and `[]` when `supported` is false (`reason` already covers every rule). A rule is declined when the date it runs from is owed but absent: a filing date, an international registration date, the Philippine statement of grant (`protection_grant_date`, for the fifth-year declaration of use of a Madrid designation), or, once the mark is registered (an expired or cancelled mark was), its registration or grant date. The Mexican third-year declaration covers grants from 10 August 2018 only, so a national mark registered before then is not asked for its grant date; a Madrid designation is, since its statement of grant can come years after its international registration. A registration-anchored rule on an application not yet registered is not declined: nothing is due yet. An expired mark names every rule whose miss costs something (its status serves a rule while the window of that rule is open), except, without `include_missed`, a one-off rule of a national mark (a declaration due once, such as US Section 8, the Philippine third- and fifth-year declarations or the Mexican third-year declaration): its window closed before the term ended, so the date would compute nothing to act on; a Madrid designation granted late in the term of its international registration still names it. Without `include_missed`, an expired national mark with no renewal on record (no `last_renewal_date`, `expiry_date` or `renewal_due_date`) does not name the Philippine declaration due at the fifth anniversary of a renewal either: no renewal began the term it belongs to. A cancelled mark names only a renewal that opens a modelled restoration window, which a Madrid designation never has: its status serves nothing else. With `include_missed`, both name every rule they owe that would return a row, missed or current, as of the computation date for some date the mark could carry, since its missed row would be returned too: a mark cancelled three years after filing is not asked for a registration date, because no Section 8 or 9 window can have closed yet. Supply the missing field and the rule is computed; whether a row is returned then depends on its window, `horizon_years` and `include_missed`, and for an expired mark on that window being open, as for any computed rule."},"sources":{"type":"array","items":{"type":"object","properties":{"citation":{"type":"string","example":"USPTO — Keeping Your Registration Alive"},"url":{"type":"string","format":"uri","example":"https://www.uspto.gov/trademarks/maintain/keeping-your-registration-alive"}},"required":["citation","url"]},"description":"Statutory sources of the jurisdiction configuration this computation used. Provenance is per jurisdiction configuration, not per rule: every rule in a jurisdiction shares this one source list, so it is carried once per item rather than on each row. For per-rule detail, join a row's `rule_id` to `GET /v1/deadline-rules`. Empty only when no configuration exists for the jurisdiction.","example":[{"citation":"USPTO — Keeping Your Registration Alive","url":"https://www.uspto.gov/trademarks/maintain/keeping-your-registration-alive"},{"citation":"15 U.S.C. § 1058(a) — registration term and affidavit requirement","url":"https://www.govinfo.gov/content/pkg/USCODE-2024-title15/html/USCODE-2024-title15-chap22-subchapI-sec1058.htm"},{"citation":"15 U.S.C. § 1059(a) — renewal and grace period","url":"https://www.govinfo.gov/content/pkg/USCODE-2024-title15/html/USCODE-2024-title15-chap22-subchapI-sec1059.htm"},{"citation":"15 U.S.C. § 1065(3) — incontestability filing period","url":"https://www.govinfo.gov/content/pkg/USCODE-2024-title15/html/USCODE-2024-title15-chap22-subchapI-sec1065.htm"},{"citation":"37 CFR § 2.160(a)(3) — Section 8 grace period","url":"https://www.ecfr.gov/api/versioner/v1/full/2026-08-28/title-37.xml?part=2"},{"citation":"37 CFR § 2.164(b) — cancellation after missed Section 8 period","url":"https://www.ecfr.gov/api/versioner/v1/full/2026-08-28/title-37.xml?part=2"},{"citation":"TMEP § 1604.04 — Time for Filing §8 Declaration","url":"https://tmep.uspto.gov/RDMS/TMEP/print?href=TMEP-1600d1e1.html&version=current"},{"citation":"37 CFR § 2.167(f) — incontestability filing period","url":"https://www.ecfr.gov/api/versioner/v1/full/2026-08-28/title-37.xml?part=2"},{"citation":"37 CFR § 2.182 — renewal filing window","url":"https://www.ecfr.gov/api/versioner/v1/full/2026-08-28/title-37.xml?part=2"},{"citation":"37 CFR § 2.185(b) — expiration after missed renewal period","url":"https://www.ecfr.gov/api/versioner/v1/full/2026-08-28/title-37.xml?part=2"},{"citation":"37 CFR § 2.196 — weekend and federal-holiday rollover","url":"https://www.ecfr.gov/api/versioner/v1/full/2026-08-28/title-37.xml?part=2"},{"citation":"TMEP § 1606.03 — renewal filing window","url":"https://tmep.uspto.gov/RDMS/TMEP/print?href=TMEP-1600d1e1.html&version=current"}]},"as_of":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Resolved calendar date used for this computation.","example":"2025-07-05"},"computed_at":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when this computation was performed.","example":"2025-07-05T12:34:56.789Z"},"support":{"type":"array","items":{"$ref":"#/components/schemas/DeadlineSupport"},"description":"Per-deadline-type capability. Present only when the item supplied `facts` (an empty array counts). Item-level `supported` describes the maintenance schedule ONLY — a US mark with no office-action facts still has a renewal schedule, so a single item-level boolean cannot answer \"can you compute my office-action deadline\"."},"prosecution_deadlines":{"type":"array","items":{"$ref":"#/components/schemas/ProsecutionDeadline"},"description":"One result per prosecution trigger instance (office action, notice of allowance) plus any office-stated deadline that hangs off none of them. Same presence rule as `support`."}},"required":["object","jurisdiction_code","filing_route","supported","reason","deadlines","unsupported_rules","sources","as_of","computed_at"]},"DeadlineComputationError":{"type":"object","properties":{"object":{"type":"string","enum":["deadline_computation_error"]},"id":{"type":["string","null"],"description":"The stored trademark ID the item named; null for a caller-facts item (one without `id`)."},"error":{"type":"object","properties":{"type":{"type":"string","description":"`not_found` (an unknown or unretrievable ID) or `validation_error`."},"code":{"type":"string","description":"Present on `validation_error`: `unknown_jurisdiction_code` when `jurisdiction` is neither an ISO 3166-1 country code nor known to the rulebook (e.g. `XX`)."},"detail":{"type":"string"}},"required":["type","detail"]}},"required":["object","id","error"]},"DeadlineComputeResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/DeadlineComputation"},{"$ref":"#/components/schemas/DeadlineComputationError"}]}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"ProsecutionMaintenanceFiling":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["section_8","section_71","section_9"]},"window_end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive last day of that filing period excluding any grace period, as `YYYY-MM-DD`: the Section 8(a)(1) or 8(a)(2) window end, the Section 71(a)(1) or 71(a)(2) window end, or, for Section 9, the registration expiration date. Do not add the grace period. Time remaining in the grace period is a separate right: file a complete new Section 8 or 71 affidavit, or a complete new Section 9 renewal application, with the grace surcharge; it does not extend the refusal response deadline, and Signa does not compute it here.","example":"2027-03-10"}},"required":["type","window_end_date"],"additionalProperties":false,"description":"The maintenance filing under examination, required by post-registration refusal-response rules (37 CFR 2.163(b) / 2.184(b)(1) / 7.39(a) \"whichever is later\"). Never derived: nothing on an Office action says which filing period is being examined, so without it the engine fails closed with `maintenance_window_not_established`."},"ProsecutionFactProvenance":{"type":"object","properties":{"source_event_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":50,"default":[]},"source_rows":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","maxLength":64},"label":{"type":"string","maxLength":256},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"stage":{"type":["string","null"],"enum":["written","mailed","notification","entered",null],"default":null}},"required":["code","label","date"],"additionalProperties":false},"maxItems":50,"default":[]}},"additionalProperties":false,"description":"Optional audit trail: the source rows this fact was collapsed from. Echoed nowhere; kept so a caller replaying stored events can carry its own provenance through the computation."},"ProsecutionFact":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-assigned identifier, unique within the item.","example":"oa-1"},"provenance":{"$ref":"#/components/schemas/ProsecutionFactProvenance"},"kind":{"type":"string","enum":["office_action"]},"family":{"type":"string","enum":["nonfinal","final","subsequent_final","examiner_amendment","ea_priority_combined","examiners_statement","priority_action","suspension_letter","suspension_inquiry"],"example":"nonfinal"},"is_final":{"type":"boolean","default":false},"operative_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date the deadline runs from. For a §66(a) provisional refusal this is the date the USPTO sent the action to the IB (TMEP 1904.02(h)), not the drafted date.","example":"2024-02-01"},"operative_date_basis":{"type":"string","enum":["mailed_row","ib_transmittal_row","written_row","caller_supplied"],"description":"Required. How the operative date was determined. Rules accept only their own bases; `caller_supplied` is the basis for facts-in offices (EUIPO stores no examination events).","example":"mailed_row"},"drafted_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"ib_transmittal_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"is_madrid_provisional_refusal":{"type":"boolean","default":false},"stated_due_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null,"description":"The deadline PRINTED on the action. 37 CFR 2.62(a) makes it authoritative over the rule period when present.","example":null}},"required":["id","kind","family","operative_date","operative_date_basis"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-assigned identifier, unique within the item.","example":"oa-1"},"provenance":{"$ref":"#/components/schemas/ProsecutionFactProvenance"},"kind":{"type":"string","enum":["oa_response"]},"filed_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"is_request_for_reconsideration":{"type":"boolean","default":false},"responds_to_office_action_id":{"type":["string","null"],"minLength":1,"maxLength":128,"default":null,"description":"The `id` of another fact in the same item, or null.","example":null},"linkage":{"type":"string","enum":["inferred","ambiguous"],"default":"inferred"}},"required":["id","kind","filed_date"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-assigned identifier, unique within the item.","example":"oa-1"},"provenance":{"$ref":"#/components/schemas/ProsecutionFactProvenance"},"kind":{"type":"string","enum":["oa_extension"]},"requested_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"granted_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"responds_to_office_action_id":{"type":["string","null"],"minLength":1,"maxLength":128,"default":null,"description":"The `id` of another fact in the same item, or null.","example":null},"linkage":{"type":"string","enum":["inferred","ambiguous"],"default":"inferred"}},"required":["id","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-assigned identifier, unique within the item.","example":"oa-1"},"provenance":{"$ref":"#/components/schemas/ProsecutionFactProvenance"},"kind":{"type":"string","enum":["notice_of_allowance"]},"issued_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"is_corrected":{"type":"boolean","default":false},"corrects_notice_of_allowance_id":{"type":["string","null"],"minLength":1,"maxLength":128,"default":null,"description":"The `id` of another fact in the same item, or null.","example":null},"withdrawn_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null}},"required":["id","kind","issued_date"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-assigned identifier, unique within the item.","example":"oa-1"},"provenance":{"$ref":"#/components/schemas/ProsecutionFactProvenance"},"kind":{"type":"string","enum":["sou"]},"filed_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"accepted_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"responds_to_notice_of_allowance_id":{"type":["string","null"],"minLength":1,"maxLength":128,"default":null,"description":"The `id` of another fact in the same item, or null.","example":null}},"required":["id","kind","filed_date"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-assigned identifier, unique within the item.","example":"oa-1"},"provenance":{"$ref":"#/components/schemas/ProsecutionFactProvenance"},"kind":{"type":"string","enum":["sou_extension"]},"ordinal":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]},{"type":"number","enum":[4]},{"type":"number","enum":[5]},{"type":"null"}],"default":null},"filed_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"granted_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"extends_notice_of_allowance_id":{"type":["string","null"],"minLength":1,"maxLength":128,"default":null,"description":"The `id` of another fact in the same item, or null.","example":null},"linkage":{"type":"string","enum":["explicit","inferred","ambiguous"],"default":"inferred"}},"required":["id","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-assigned identifier, unique within the item.","example":"oa-1"},"provenance":{"$ref":"#/components/schemas/ProsecutionFactProvenance"},"kind":{"type":"string","enum":["suspension"]},"subtype":{"type":"string","enum":["letter","inquiry","periodic_check"]},"operative_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"responded_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null}},"required":["id","kind","subtype","operative_date"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-assigned identifier, unique within the item.","example":"oa-1"},"provenance":{"$ref":"#/components/schemas/ProsecutionFactProvenance"},"kind":{"type":"string","enum":["abandonment"]},"reason":{"type":"string","enum":["failure_to_respond","express","after_publication","after_inter_partes","after_appeal","no_use_statement","defective_use_statement","other"]},"abandoned_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"notice_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"follows_office_action_id":{"type":["string","null"],"minLength":1,"maxLength":128,"default":null,"description":"The `id` of another fact in the same item, or null.","example":null},"follows_notice_of_allowance_id":{"type":["string","null"],"minLength":1,"maxLength":128,"default":null,"description":"The `id` of another fact in the same item, or null.","example":null},"linkage":{"type":"string","enum":["inferred","ambiguous"],"default":"inferred"}},"required":["id","kind","reason","abandoned_date"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-assigned identifier, unique within the item.","example":"oa-1"},"provenance":{"$ref":"#/components/schemas/ProsecutionFactProvenance"},"kind":{"type":"string","enum":["petition_to_revive"]},"filed_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"granted_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null}},"required":["id","kind"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":128,"description":"Caller-assigned identifier, unique within the item.","example":"oa-1"},"provenance":{"$ref":"#/components/schemas/ProsecutionFactProvenance"},"kind":{"type":"string","enum":["stated_deadline"]},"office_code":{"type":"string","minLength":1,"maxLength":16,"description":"ST.3 code of the office that stated the deadline.","example":"CN"},"stated_due_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"stated_period":{"type":["object","null"],"properties":{"value":{"type":"integer","minimum":1,"maximum":120},"unit":{"type":"string","enum":["month","day"]}},"default":null,"required":["value","unit"],"additionalProperties":false},"basis":{"type":"string","enum":["office_issue_date","office_to_ib_send_date","ib_to_holder_transmittal_date","holder_receipt_date","explicit_dates"]},"begin_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"end_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","default":null},"relates_to_office_action_id":{"type":["string","null"],"minLength":1,"maxLength":128,"default":null,"description":"The `id` of another fact in the same item, or null.","example":null},"linkage":{"type":"string","enum":["explicit","inferred","ambiguous"],"default":"explicit"}},"required":["id","kind","office_code","basis"],"additionalProperties":false}]},"DeadlineComputeItem":{"type":"object","properties":{"jurisdiction":{"type":"string","minLength":1,"description":"Deadline jurisdiction code: an ISO 3166-1 alpha-2 country code, EU or WO (the Madrid international registration). Aliases are read as their jurisdiction and answered with it (EM is read as EU, UK as GB, WIPO as WO). A code that is neither a country code nor known to the rulebook fails only that item, as a `deadline_computation_error` with `error.code` `unknown_jurisdiction_code`; a real jurisdiction with no modeled rules answers `supported: false` with `unsupported_jurisdiction`.","example":"US"},"filing_route":{"type":"string","enum":["national","regional","madrid"],"description":"Filing route. Defaults to national.","example":"national"},"status":{"type":"string","enum":["filed","examining","pending_publication","published","opposition_period","pending_opposition","pending_cancellation","pending_issuance","registered","allowed","abandoned","withdrawn","surrendered","refused","cancelled","invalidated","expired","unknown"],"description":"Trademark status. Defaults to registered.","example":"registered"},"filing_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2019-01-15"},"priority_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Earliest Paris/WTO convention priority date, as YYYY-MM-DD. Used only by jurisdictions whose statute registers a convention application AS OF that date, so that the statutory term runs from it — India (Trade Marks Act 1999 s. 154(2)) is the only one today. Everywhere else it is ignored. Omit it and India falls back to filing_date (s. 23(1)).","example":null},"registration_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2020-03-10"},"grant_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Grant date as YYYY-MM-DD. When omitted, `registration_date` from the same item is used as the grant date for BR and MX items with filing_route \"national\" (the default when filing_route is omitted); an explicit grant_date always wins. An item carrying ANY Madrid marker (filing_route `madrid`, designation_date, protection_grant_date, international_registration_date or international_registration_number) is treated as Madrid-provenanced and never takes the fallback, matching the stored answer. Send filing_route \"madrid\" for designations.","example":null},"expiry_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Office-stated end of the current term. When provided, renewal deadlines anchor on it (trigger_field \"reported_expiry\") unless the statutory ladder from the trigger date already passes through it. An office-stated renewal-due date (renewal_due_date_basis \"reported\") anchors the same way when no expiry is stored (trigger_field \"reported_renewal_due\"). When it (or the renewal-due date anchoring in its place) has passed, together with its grace period and any restoration window, and no supplied `last_renewal_date` renewed that cycle, the term ended there and no row of a later cycle (renewal, declaration or restoration) is returned.","example":null},"renewal_due_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":null},"last_renewal_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date the registration was last renewed, as YYYY-MM-DD. In every jurisdiction, the earliest renewal cycle whose filing window holds the date and every earlier cycle are treated as paid and leave the schedule (never the cycle ending at an office-stated current expiry, which the renewal extended the term to). For Canada it also selects the Trademarks Regulations SOR/2018-227 s. 159 cycle (\"the first renewal, on or after the coming-into-force day\" of 17 June 2019): a Canadian registration whose term ended shortly before that day but whose fee was paid in the grace period on or after it is the s. 159 renewal, and its window opens at the period start. Omit it and Canada falls back to the cycle due date, which is right except in that cohort.","example":null},"register_type":{"type":["string","null"],"enum":["principal","supplemental",null],"description":"US only: the register the mark is on. `supplemental` drops the Section 15 declaration of incontestability, which 15 USC 1094 does not allow for Supplemental Register registrations. Omit it, or send `principal`, and Section 15 is computed as before. Ignored in every other jurisdiction.","example":null},"designation_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":null},"protection_grant_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":null},"international_registration_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":null},"international_registration_number":{"type":["string","null"],"maxLength":64,"description":"WIPO international registration number, when the record has one. Never parsed as a date and never used in arithmetic: its only effect is to mark the item as Madrid-provenanced, which vetoes the BR/MX `registration_date`-as-`grant_date` fallback exactly as `designation_date`, `protection_grant_date`, `international_registration_date` and `filing_route: \"madrid\"` do. Supplying it makes this endpoint agree with the stored answer for a mark that carries no Madrid DATE.","example":null},"maintenance_filing":{"$ref":"#/components/schemas/ProsecutionMaintenanceFiling"},"facts":{"type":"array","items":{"$ref":"#/components/schemas/ProsecutionFact"},"maxItems":100,"description":"Optional prosecution fact instances (office actions, notices of allowance, responses, extensions, abandonments, office-stated deadlines). When present, prosecution deadlines are computed per instance and returned on `prosecution_deadlines`, alongside a per-deadline-type `support` report. Omit the field entirely and the item carries neither `prosecution_deadlines` nor `support`; every other field, including the rule-identity provenance (`sources`, `as_of`, `computed_at`), is returned either way. Send `[]` to opt in to the capability report without supplying any facts."}},"required":["jurisdiction"],"additionalProperties":false},"DeadlineComputeIdItem":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Stored trademark ID. Resolves maintenance inputs and prosecution event facts server-side."}},"required":["id"],"additionalProperties":false},"DeadlineComputeRequest":{"type":"object","properties":{"items":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/DeadlineComputeItem"},{"$ref":"#/components/schemas/DeadlineComputeIdItem"}]},"minItems":1},"as_of_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Calendar date to compute relative to. Defaults to today.","example":"2025-07-05"},"horizon_years":{"type":"integer","minimum":1,"maximum":20,"description":"Deadline horizon in years, up to 20 (the horizon of every trademark `derived` block). Defaults to 5.","example":5},"include_optional":{"type":"boolean","description":"Whether to include optional deadlines. Defaults to true.","example":true},"include_missed":{"type":"boolean","description":"Whether to include missed deadlines. Defaults to false. A renewal cycle the office data proves paid (before the office-stated expiry, or paid by `last_renewal_date`) is never returned as missed.","example":false}},"required":["items"],"additionalProperties":false},"DeadlineListRow":{"allOf":[{"$ref":"#/components/schemas/DeadlineRow"},{"type":"object","properties":{"trademark_id":{"type":"string","example":"tm_7d4e1f2a3b8c9d0e"},"mark_text":{"type":["string","null"]},"office_code":{"type":["string","null"],"example":"US"},"application_number":{"type":["string","null"],"description":"The mark's application number at its office.","example":"97123456"},"registration_number":{"type":["string","null"],"description":"The mark's registration number at its office; null before registration.","example":"6123456"},"ir_number":{"type":["string","null"],"description":"The international registration number of a Madrid record (without leading zeros), so the rows of one IR and its designations can be grouped; null otherwise.","example":"551089"},"urgency":{"type":"string","enum":["critical","upcoming","routine","in_grace","missed"],"description":"How close the row is at the pinned computation date; what the `urgency` filter selects on.","example":"routine"},"effective_from":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Earliest authoritative date for the rule, or null when no boundary is established.","example":null},"last_verified":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date the parent jurisdiction configuration was last verified.","example":"2026-03-10"},"sources":{"type":"array","items":{"type":"object","properties":{"citation":{"type":"string","example":"USPTO — Keeping Your Registration Alive"},"url":{"type":"string","format":"uri","example":"https://www.uspto.gov/trademarks/maintain/keeping-your-registration-alive"}},"required":["citation","url"]},"description":"Statutory sources behind the rule that produced this row — the same citations `POST /v1/deadlines/compute` returns for the jurisdiction configuration."}},"required":["trademark_id","mark_text","office_code","application_number","registration_number","ir_number","urgency","effective_from","last_verified","sources"]}]},"DeadlineUnsupportedMark":{"type":"object","properties":{"trademark_id":{"type":"string","example":"tm_7d4e1f2a3b8c9d0e"},"supported":{"type":"boolean","description":"`false`: no schedule was computed for this mark, so it has no rows (see `reason`). `true`: its schedule was computed but some rules were declined (see `unsupported_rules`)."},"reason":{"type":["string","null"],"enum":["unsupported_jurisdiction","requires_office_date",null],"description":"Same vocabulary as `reason` on POST /v1/deadlines/compute. `unsupported_jurisdiction`: no rules are modeled for the jurisdiction. `requires_office_date`: the record does not carry the input the statute needs and the office has stated no expiry to anchor on. `null` when `supported` is true."},"unsupported_rules":{"type":"array","items":{"$ref":"#/components/schemas/UnsupportedDeadlineRule"},"description":"Rules declined for want of their statutory anchor, as on POST /v1/deadlines/compute: without `include_missed`, or with it when the list is filtered to `urgency=missed` (the only filter that serves missed rows). `[]` when `supported` is false. Rules with reason `computed_on_office_leg` are not listed, and alone never put a mark here: the designated office's own record serves them (trademark detail and POST /v1/deadlines/compute still name them)."}},"required":["trademark_id","supported","reason","unsupported_rules"]},"DeadlineListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DeadlineListRow"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"unsupported_marks":{"type":["array","null"],"items":{"$ref":"#/components/schemas/DeadlineUnsupportedMark"},"description":"Marks in the requested scope whose deadlines could not be computed (they have no rows) or were computed only in part (some rules declined), sorted by `trademark_id`. A mark whose status ends every obligation (`abandoned`, `withdrawn`, `surrendered`, `invalidated`, or `refused` other than a WIPO international registration) is never listed: it is owed no deadlines in any jurisdiction. Neither is a WIPO record of a US designation whose only declined rules are `computed_on_office_leg`: the USPTO record of the designation serves them. Covers the whole portfolio or trademark, not just this page, and ignores the `type` and `due_before` filters and every `urgency` value but `missed`, which also names the rules declined for missed rows. Reported on the first page (a request without `cursor`); `null` on every continuation page, because the cursor pins the computation date and the first page already answered for the whole chain. `[]` on a first page means every mark in scope that is owed deadlines was fully computed."},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Stable warning code. `horizon_truncated`: `due_before` is more than 5 years after the computation date, and deadlines are computed only 5 years ahead, so rows due after the horizon are not listed.","example":"horizon_truncated"},"message":{"type":"string","description":"Human-readable explanation, naming the horizon date."}},"required":["code","message"]},"description":"Present only when the list carries a caveat; see `code`."},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","unsupported_marks","request_id"]},"FeeSource":{"type":"object","properties":{"citation":{"type":"string"},"url":{"type":"string"},"snapshot_path":{"type":"string"},"snapshot_sha256":{"type":"string"},"quote":{"type":"string"}},"required":["citation","url","snapshot_path","snapshot_sha256","quote"]},"FeeRule":{"type":"object","properties":{"fee_id":{"type":"string"},"office":{"type":"string","enum":["WO","US","EM","GB"]},"route":{"type":"string","enum":["direct","madrid"]},"action":{"type":"string","enum":["filing","renewal","declaration_of_use","declaration_of_incontestability","statement_of_use","amendment_to_allege_use","sou_extension","opposition","oa_extension","expungement_oa_extension","petition_to_revive","restoration","continuation","restitutio","subsequent_designation","transfer","name_address_change","limitation","licence","division"]},"description":{"type":"string"},"component":{"type":"string","enum":["base","additional_class","surcharge","individual_designation","complementary","supplementary","discount","series"]},"filing_channel":{"type":"string","enum":["electronic","paper","any"]},"amount_minor":{"type":["integer","null"],"minimum":0},"currency":{"type":"string","enum":["USD","EUR","GBP","CHF"]},"unit":{"type":"string","enum":["per_mark","per_class","per_party","per_1000_characters"]},"per_class_increment_minor":{"type":["integer","null"],"minimum":0},"classes_included_in_base":{"type":["integer","null"]},"class_range":{"type":["object","null"],"properties":{"from":{"type":"integer"},"through":{"type":["integer","null"]}},"required":["from","through"]},"surcharge":{"oneOf":[{"type":"object","properties":{"shape":{"type":"string","enum":["flat"]},"amount_minor":{"type":"integer","minimum":0}},"required":["shape","amount_minor"]},{"type":"object","properties":{"shape":{"type":"string","enum":["percent"]},"rate_percent":{"type":"number"},"basis_fee_ids":{"type":"array","items":{"type":"string"}},"cap_amount_minor":{"type":["integer","null"],"minimum":0},"rounding":{"type":"string","enum":["minor_unit_half_up","whole_unit_half_up"]},"basis_resolved":{"type":"boolean"}},"required":["shape","rate_percent","basis_fee_ids","cap_amount_minor","rounding","basis_resolved"]},{"type":"object","properties":{"shape":{"type":"string","enum":["per_class"]},"amount_minor":{"type":"integer","minimum":0}},"required":["shape","amount_minor"]},{"type":"object","properties":{"shape":{"type":"string","enum":["per_month"]},"amount_minor":{"type":"integer","minimum":0},"part_month_counts":{"type":"boolean"},"max_months":{"type":["integer","null"]}},"required":["shape","amount_minor","part_month_counts","max_months"]},{"type":"object","properties":{"shape":{"type":"string","enum":["distinct_fee"]},"fee_id":{"type":"string"}},"required":["shape","fee_id"]},{"type":"null"}]},"fee_schedule_id":{"type":"string"},"effective_from":{"type":"string"},"effective_from_basis":{"type":"string","enum":["schedule_in_force","verified_applicability"]},"effective_to":{"type":["string","null"]},"last_verified":{"type":"string"},"verification_expires_at":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/FeeSource"}},"reviewers":{"type":"array","items":{"type":"string"}},"evidence_fee_id":{"type":"string"},"applies_when":{"type":"object","properties":{"colour":{"type":"boolean"},"ldc_eligible":{"type":"boolean"},"gb_schedule":{"type":"string","enum":["old","new"]},"gb_transition":{"type":"string","enum":["application","renewal","payment"]},"no_individual_fee":{"type":"boolean"}}}},"required":["fee_id","office","route","action","description","component","filing_channel","amount_minor","currency","unit","per_class_increment_minor","classes_included_in_base","class_range","surcharge","fee_schedule_id","effective_from","effective_from_basis","effective_to","last_verified","verification_expires_at","sources","reviewers","evidence_fee_id","applies_when"]},"FeeListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/FeeRule"}},"has_more":{"type":"boolean","enum":[false]},"pagination":{"type":"object","properties":{"cursor":{"type":"null"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination"]},"FeeEstimateLine":{"type":"object","properties":{"status":{"type":"string","enum":["included","unsupported_office","unsupported_action","missing_input","unsupported_date","unverified_component"]},"office":{"type":"string"},"description":{"type":"string"},"fee_id":{"type":["string","null"]},"fee_schedule_id":{"type":["string","null"]},"effective_from":{"type":["string","null"]},"last_verified":{"type":["string","null"]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/FeeSource"}},"quantity":{"type":["number","null"]},"amount_minor":{"type":["integer","null"],"minimum":0},"currency":{"type":["string","null"],"enum":["USD","EUR","GBP","CHF",null]}},"required":["status","office","description","fee_id","fee_schedule_id","effective_from","last_verified","sources","quantity","amount_minor","currency"]},"FeeEstimate":{"type":"object","properties":{"object":{"type":"string","enum":["fee_estimate"]},"office":{"type":"string"},"route":{"type":"string","enum":["direct","madrid"]},"action":{"type":"string","enum":["filing","renewal","declaration_of_use","declaration_of_incontestability","statement_of_use","amendment_to_allege_use","sou_extension","opposition","oa_extension","expungement_oa_extension","petition_to_revive","restoration","continuation","restitutio","subsequent_designation","transfer","name_address_change","limitation","licence","division"]},"classes":{"type":"integer","minimum":1,"maximum":45},"as_of":{"type":"string"},"dataset_version":{"type":"string"},"complete":{"type":"boolean"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FeeEstimateLine"}},"currency":{"type":["string","null"],"enum":["USD","EUR","GBP","CHF",null]},"total_minor":{"type":["integer","null"],"minimum":0,"description":"Complete total in native currency minor units; null when any component is unresolved."},"subtotal_minor":{"type":"integer","minimum":0,"description":"Sum of included components only, even when the total is unknown."},"omissions":{"type":"array","items":{"type":"string"}},"assumptions":{"type":"array","items":{"type":"string"}}},"required":["object","office","route","action","classes","as_of","dataset_version","complete","lines","currency","total_minor","subtotal_minor","omissions","assumptions"]},"FeeEstimateResponse":{"allOf":[{"$ref":"#/components/schemas/FeeEstimate"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"FeeEstimateRequest":{"type":"object","properties":{"office":{"type":"string","minLength":1,"maxLength":64,"description":"Office code (WO, US, EM, GB). The platform office codes WIPO, USPTO, EUIPO (also EU), and UKIPO (also UK) are accepted as aliases for WO, US, EM, and GB. Unsupported offices return an incomplete estimate."},"route":{"type":"string","enum":["direct","madrid"]},"action":{"type":"string","enum":["filing","renewal","declaration_of_use","declaration_of_incontestability","statement_of_use","amendment_to_allege_use","sou_extension","opposition","oa_extension","expungement_oa_extension","petition_to_revive","restoration","continuation","restitutio","subsequent_designation","transfer","name_address_change","limitation","licence","division"]},"classes":{"anyOf":[{"type":"integer","minimum":1,"maximum":45},{"type":"array","items":{"type":"integer","minimum":1,"maximum":45},"minItems":1,"maxItems":45}]},"designations":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":200},"colour":{"type":"boolean"},"applicant":{"type":"object","properties":{"ldc_eligible":{"type":"boolean","description":"Caller attests that all eligibility predicates in the WIPO least-developed-country fee-reduction footnote hold for every applicant."}},"required":["ldc_eligible"],"additionalProperties":false},"filing_channel":{"type":"string","enum":["electronic","paper"]},"payment_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"renewal_due_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"application_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"application_in_payment_grace":{"type":"boolean"},"late":{"type":"boolean"}},"required":["office","route","action","classes"],"additionalProperties":false},"OppositionCommonExtension":{"type":["object","null"],"properties":{"days":{"type":["integer","null"],"example":30},"months":{"type":["integer","null"],"example":null},"as_of_right":{"type":"boolean","example":true},"notes":{"type":"string","example":"First 30-day extension granted automatically on timely request."}},"required":["days","months","as_of_right","notes"]},"OppositionWindowSource":{"type":["object","null"],"properties":{"citation":{"type":"string","example":"Article 46(1) EUTMR (Regulation (EU) 2017/1001)"},"url":{"type":"string","format":"uri","example":"https://eur-lex.europa.eu/eli/reg/2017/1001/oj/eng"}},"required":["citation","url"]},"OppositionWindowComputation":{"type":"object","properties":{"object":{"type":"string","enum":["opposition_window"]},"supported":{"type":"boolean"},"rule_id":{"type":["string","null"],"description":"Stable opaque rule slug of the opposition rule resolved for this office and filing route. Populated whenever a rule was resolved, including on unsupported items where the window could not be computed. Null only when no rule exists for the office and route.","example":"eu_opposition"},"effective_from":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Earliest date from which the rule's modelled content is authoritative, or null when the corpus establishes none. Populated alongside rule_id, including on unsupported items: when a publication date precedes it, the rule does not reach that date and the item is reported as unsupported_office.","example":null},"jurisdiction_code":{"type":["string","null"],"example":"EU"},"office_code":{"type":["string","null"],"example":"EM"},"filing_route":{"type":["string","null"],"enum":["domestic","madrid_designation",null],"example":"domestic"},"publication_date":{"type":["string","null"],"example":"2026-05-01"},"window_opens":{"type":["string","null"],"example":"2026-05-02"},"window_closes":{"type":["string","null"],"example":"2026-08-03"},"close_adjustment":{"type":["string","null"],"enum":["moved","unchanged","not_checked","month_end_overflow",null],"description":"Whether `window_closes` was checked against the office's holiday calendar, and whether that check moved it. `moved`: the close fell on a day the office is shut and was rolled forward to the next business day. `unchanged`: the calendar was consulted and the arithmetic close was already a business day. `not_checked`: no pinned closure list verified this date. The close falls outside the calendar's pinned coverage years (the deterministic weekend and fixed-holiday roll may still have been applied), the rule ships without a calendar, or there is no publication date. The true close can only be the same or LATER, so a `not_checked` close is correct-or-EARLY: treat it as indeterminate near the boundary rather than as a decided open/closed answer. `month_end_overflow`: the window ran into the following calendar month because its end day number does not exist in the target one, and that reason subsumes any roll applied afterwards. Null only when no window was computed.","example":"unchanged"},"status":{"type":["string","null"],"enum":["not_started","open","closed","unknown",null],"example":"open"},"days_until_open":{"type":["integer","null"],"example":null},"days_remaining":{"type":["integer","null"],"example":29},"office_time_zone":{"type":["string","null"],"example":"Europe/Madrid"},"trigger_event":{"type":["string","null"],"enum":["application_publication","registration_publication","international_designation_publication",null],"example":"application_publication"},"rule_version":{"type":["string","null"],"example":"2026-05-06"},"common_extension":{"$ref":"#/components/schemas/OppositionCommonExtension"},"source":{"$ref":"#/components/schemas/OppositionWindowSource"},"reason":{"type":["string","null"],"description":"Why the window is unsupported or degraded, as a snake_case code; null on every normal window. With `supported: false`: `unsupported_office` (no rule exists for this office and route), `before_commencement` (a rule exists, but the publication date, or a sent `filing_date`, falls before the date it applies from; `rule_id` names it and `effective_from` the boundary) or `window_not_computable` (a rule resolved but no window could be produced). With `supported: true`, a degraded window: `publication_date_kind_mismatch`, meaning the `publication_date_kind` you sent is not the publication the matched Madrid rule runs from, including the explicit `unknown`. A plain missing `publication_date` stays reason-less: `status: \"unknown\"` with a null `publication_date` already says that. Treat the vocabulary as open — new codes may be added, so branch on the codes you know and fall through on the rest.","example":null}},"required":["object","supported","rule_id","effective_from","jurisdiction_code","office_code","filing_route","publication_date","window_opens","window_closes","close_adjustment","status","days_until_open","days_remaining","office_time_zone","trigger_event","rule_version","common_extension","source","reason"]},"OppositionComputeResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/OppositionWindowComputation"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"OppositionComputeItem":{"type":"object","properties":{"office":{"type":"string","minLength":1,"description":"Trademark office — WIPO ST.3 code (e.g. US, EM, BX), any case. Legacy codes (uspto, euipo, …) and the EU alias are also accepted. Unrecognized tokens are passed through (not rejected) and return `unsupported_office`, as do offices without modeled opposition rules.","example":"EM"},"filing_route":{"type":"string","enum":["national","regional","madrid"],"description":"Filing route. Defaults to national.","example":"national"},"publication_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication calendar date. Omit when the publication date is unknown.","example":"2026-05-01"},"filing_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Application filing calendar date. Read only by rules whose era pivot is keyed on the filing date (TR: SMK geçici m. 1/1 gives applications filed before 2017-01-10 the former 3-month window even when published later). Omit it and such a rule falls back to the publication date, which yields the shorter modern window. Also read by a rule that excludes marks already filed when its opposition procedure commenced (CH: filed before 1993-04-01; PL: filed before 2016-04-15), which then has no window; omit it and only the publication date is tested against the commencement. Every other rule ignores it.","example":"2026-01-15"},"publication_date_kind":{"type":"string","enum":["office_journal","wipo_gazette","office_register","unknown"],"description":"Which publication `publication_date` is. A Madrid designation has two — WIPO's Gazette of International Marks, and the designated office's own journal republication — and offices run their opposition clock from different ones. The adjudicated Madrid rules today: FR, CH and DE run from the WIPO Gazette (`wipo_gazette`); AU, CA, EU, FI, NO, PL, SG and US from their own journal (`office_journal`). Supply it and a rule that needs the OTHER publication returns `status: \"unknown\"` with null dates, and `reason: \"publication_date_kind_mismatch\"`, instead of a wrong statutory bar. `unknown` is NOT the same as omitting the field: it is a positive statement that you looked and the source did not establish which publication the date is, and on an adjudicated Madrid rule that provenance is refused for the same reason a mismatch is. OMIT the field and the window is computed exactly as before — that is the only value-free option. Ignored on the national and regional filing routes, where there is no second candidate publication.","example":"office_journal"}},"required":["office"],"additionalProperties":false},"OppositionComputeRequest":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OppositionComputeItem"},"minItems":1},"as_of_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Office-local calendar date to compute relative to. Defaults to today.","example":"2026-07-05"}},"required":["items"],"additionalProperties":false},"ReconcileFieldDiff":{"type":"object","properties":{"field":{"type":"string","enum":["status","owner_name","mark_text","filing_date","registration_date","expiry_date","renewal_due_date","registration_number","nice_classes"]},"your_value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"integer"}}]},"register_value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"integer"}},{"type":"null"}]},"match":{"type":["boolean","null"],"description":"Whether your value matches the register value after field-specific normalization. `null` when the office does not publish the field at all (USPTO expiry and renewal dates; most offices publish no renewal due date): no evidence either way, so it never counts toward `mismatch_count` or `result`. A register with no value for a field the office does publish (a pending application has no registration number yet) is `false`. With `verdict_detail: true`, `field_verdicts` carries the computed date for expiry and renewal fields."}},"required":["field","your_value","register_value","match"]},"ReconcileLookup":{"type":"object","properties":{"office":{"type":"string","description":"Public ST.3 code, post-resolution.","example":"US"},"office_input":{"type":"string","description":"The office token you actually sent, verbatim.","example":"uspto"},"application_number":{"type":["string","null"]},"registration_number":{"type":["string","null"]},"matched_on":{"type":"string","enum":["application_number","registration_number","both"]},"identifier_normalization":{"type":"string","enum":["none","separators_removed"],"description":"How your identifiers were normalized before lookup. `none`: identifiers are matched as sent, except Madrid registration numbers, which also match the stored WO-prefixed and zero-padded forms. `separators_removed`: the numbers as sent found nothing, so spaces, commas, periods, slashes and hyphens were removed (`73/273,292` became `73273292`) and `application_number` / `registration_number` here are the numbers looked up. Only a result made of digits is tried. Treat the values as an open list."}},"required":["office","office_input","application_number","registration_number","matched_on","identifier_normalization"],"description":"Present only when `verdict_detail: true`: how your identifiers were interpreted."},"ReconcileComputedContext":{"type":"object","properties":{"jurisdiction_code":{"type":"string","example":"US"},"filing_route":{"type":"string","enum":["national","regional","madrid"]},"supported":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["unsupported_jurisdiction","requires_office_date",null],"description":"Why no maintenance schedule was computed; null when `supported` is true. Same vocabulary as POST /v1/deadlines/compute with `include_missed: true`, read on the schedule reconcile matches against: missed cycles and the cycles a recorded renewal paid. So a record with a renewal on record can read `requires_office_date` here, where compute reads `supported: true`, when it lacks the office date that dates those paid cycles."},"sources":{"type":"array","items":{"type":"object","properties":{"citation":{"type":"string","example":"15 U.S.C. §1058"},"url":{"type":"string"}},"required":["citation","url"]}},"as_of":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-09-11"},"computed_at":{"type":"string","format":"date-time","example":"2026-09-11T11:02:33.418Z"},"horizon_years":{"type":"integer","example":10},"unsupported_rules":{"type":"array","items":{"$ref":"#/components/schemas/UnsupportedDeadlineRule"},"description":"Rules that apply to the record but were declined because it lacks the date the statute anchors them on, as on POST /v1/deadlines/compute with `include_missed: true` (an expired or cancelled record also names the rules whose missed cycles it cannot date), plus the rules whose renewal-paid cycles it cannot date, since reconcile matches against those cycles too. So a docketed deadline of such a rule has no computed value. A rule with reason `computed_on_office_leg` is computed on the designated office's own record instead (a WIPO record of a US designation): reconcile it against that record. `[]` when none, and `[]` when `supported` is false."}},"required":["jurisdiction_code","filing_route","supported","reason","sources","as_of","computed_at","horizon_years","unsupported_rules"],"description":"Present only when `verdict_detail: true` and the record was found: the computed-schedule context."},"ReconcileComputedProvenance":{"type":["object","null"],"properties":{"rule_id":{"type":"string","example":"us_renewal_s9"},"effective_from":{"type":["string","null"]},"last_verified":{"type":"string","example":"2026-08-14"},"due_date_adjustment":{"type":"string","enum":["moved","unchanged","not_checked","month_end_overflow"]},"grace_expiry_adjustment":{"type":"string","enum":["moved","unchanged","not_checked","month_end_overflow"]},"holiday_calendar":{"type":["string","null"],"example":"uspto_dc"}},"required":["rule_id","effective_from","last_verified","due_date_adjustment","grace_expiry_adjustment","holiday_calendar"]},"ReconcileFieldVerdict":{"type":"object","properties":{"field":{"type":"string","enum":["status","owner_name","mark_text","filing_date","registration_date","expiry_date","renewal_due_date","registration_number","nice_classes","docketed_deadline"]},"deadline_type":{"type":["string","null"],"enum":["renewal","declaration_of_use","combined_renewal_and_use","declaration_of_incontestability","restoration","international_renewal",null],"description":"Set on `docketed_deadline` rows only; null on the nine v1 field rows."},"index":{"type":["integer","null"],"minimum":0,"description":"Your index into `your_fields.docketed_deadlines` for `docketed_deadline` rows; null otherwise."},"your_value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"integer"}}]},"register_value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"integer"}},{"type":"null"}]},"computed_value":{"type":["string","null"],"example":"2030-03-10"},"basis":{"type":"string","enum":["register","computed","register_and_computed","none"],"description":"Which sources produced a value for this field."},"verdict":{"type":"string","enum":["agrees","caller_differs","register_differs_from_computed","all_differ","unsupported_jurisdiction","insufficient_data","not_computable"]},"computed_unavailable_reason":{"type":["string","null"],"enum":["not_modelled","unsupported_jurisdiction","insufficient_data",null],"description":"Non-null exactly when no computed counterpart could be produced."},"computed_provenance":{"$ref":"#/components/schemas/ReconcileComputedProvenance"}},"required":["field","deadline_type","index","your_value","register_value","computed_value","basis","verdict","computed_unavailable_reason","computed_provenance"]},"ReconcileVerdictCounts":{"type":"object","properties":{"agrees":{"type":"integer","minimum":0},"caller_differs":{"type":"integer","minimum":0},"register_differs_from_computed":{"type":"integer","minimum":0},"all_differ":{"type":"integer","minimum":0},"unsupported_jurisdiction":{"type":"integer","minimum":0},"insufficient_data":{"type":"integer","minimum":0},"not_computable":{"type":"integer","minimum":0}},"required":["agrees","caller_differs","register_differs_from_computed","all_differ","unsupported_jurisdiction","insufficient_data","not_computable"],"description":"Present only when `verdict_detail: true`: totals over `field_verdicts[]`, every key explicit."},"Reconciliation":{"type":"object","properties":{"object":{"type":"string","enum":["reconciliation"]},"office":{"type":"string","example":"US"},"application_number":{"type":["string","null"],"example":"88123456"},"registration_number":{"type":["string","null"],"example":"6012345"},"result":{"type":"string","enum":["match","mismatch","not_found","ambiguous"]},"trademark_id":{"type":["string","null"],"example":"tm_018f2f1b-2f15-7d4b-9e3c-b8b5a5c9b012"},"register_last_updated_at":{"type":["string","null"],"format":"date-time","example":"2026-07-05T12:00:00.000Z"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/ReconcileFieldDiff"}},"mismatch_count":{"type":"integer","minimum":0,"description":"Number of `fields[]` entries where `match` is `false`. A `null` match is not counted."},"match_count":{"type":"integer","minimum":2,"description":"Present only for ambiguous identifier lookups; capped at 2+.","example":2},"lookup":{"$ref":"#/components/schemas/ReconcileLookup"},"computed":{"$ref":"#/components/schemas/ReconcileComputedContext"},"field_verdicts":{"type":"array","items":{"$ref":"#/components/schemas/ReconcileFieldVerdict"},"description":"Present only when `verdict_detail: true`: one three-source verdict per field you supplied. `result` and `mismatch_count` are unaffected — they remain driven by `fields[]` alone."},"verdict_counts":{"$ref":"#/components/schemas/ReconcileVerdictCounts"}},"required":["object","office","application_number","registration_number","result","trademark_id","register_last_updated_at","fields","mismatch_count"]},"ReconcileResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Reconciliation"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"DocketedDeadline":{"type":"object","properties":{"type":{"type":"string","enum":["renewal","declaration_of_use","combined_renewal_and_use","declaration_of_incontestability","restoration","international_renewal"],"description":"Deadline type in the rulebook vocabulary (same values as the deadlines API).","example":"renewal"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2030-03-10"}},"required":["type","date"],"additionalProperties":false},"ReconcileYourFields":{"type":"object","properties":{"status":{"type":"string","minLength":1,"description":"Caller status value. Primary statuses compare against status_primary; stage statuses compare against status_stage; unknown values are reported as mismatches.","example":"active"},"owner_name":{"type":"string","minLength":1,"example":"NIKE, Inc."},"mark_text":{"type":"string","minLength":1,"example":"AIR JORDAN"},"filing_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2019-01-15"},"registration_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2020-03-10"},"expiry_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2030-03-10"},"renewal_due_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2030-03-10"},"registration_number":{"type":"string","minLength":1,"example":"6012345"},"nice_classes":{"type":"array","items":{"type":"integer"},"example":[18,25]},"docketed_deadlines":{"type":"array","items":{"$ref":"#/components/schemas/DocketedDeadline"},"minItems":1,"maxItems":10,"description":"Your docketed maintenance deadlines for this mark. Requires `verdict_detail: true`. Each entry is matched independently against the computed schedule (nearest due date within the same type) and produces its own `field_verdicts[]` row.","example":[{"type":"renewal","date":"2030-03-10"}]}},"additionalProperties":false},"ReconcileItem":{"type":"object","properties":{"office":{"type":"string","minLength":1,"description":"Trademark office — WIPO ST.3 code (e.g. US, EM, WO), any case. Legacy codes (uspto, euipo, …) and the EU alias are also accepted.","example":"US"},"application_number":{"type":"string","minLength":1,"example":"88123456"},"registration_number":{"type":"string","minLength":1,"example":"6012345"},"your_fields":{"$ref":"#/components/schemas/ReconcileYourFields"}},"required":["office","your_fields"],"additionalProperties":false},"ReconcileRequest":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ReconcileItem"},"minItems":1},"verdict_detail":{"type":"boolean","description":"Opt in to the three-source per-field verdict (`field_verdicts[]`, `computed`, `lookup`). Defaults to false. Additive: `fields[]`, `result`, `mismatch_count` and every other v1 field are unchanged. Required to send `your_fields.docketed_deadlines`.","example":true}},"required":["items"],"additionalProperties":false},"ScreeningVersions":{"type":"object","properties":{"rules":{"type":"string","description":"Served ScreeningStrategy id.","example":"screening-v1"},"scorer":{"type":"string","example":"screening-v2-scorer-v3"},"strength":{"type":"string","example":"strength-v1"},"litigation":{"type":"string","example":"litigation-v1"},"semantics":{"type":"integer","description":"Feature-semantics version.","example":3},"assets":{"type":"array","items":{"type":"string"},"description":"Sorted runtime assets. Each entry is either a filename or filename@<content_sha256> when a content digest is available.","example":["fame.v1.json@d9b6d6b7cf31968577213d33380fe1fcf8c5efbff24d9671cd44418c33c211fc","nice-class-relatedness.v1.json"]},"lane_plan":{"type":"string","example":"lane-plan-v1"},"catalog":{"type":"string","description":"Reason-catalog version.","example":"1.0.0"},"coverage_registry":{"type":"string","example":"coverage-registry-v1"},"cache_shape":{"type":"string","example":"c3-terrexp-1"},"corpus_watermarks":{"type":"object","additionalProperties":{"type":"object","properties":{"as_of":{"type":["string","null"]},"status":{"type":"string"}},"required":["as_of","status"]},"description":"Per-office corpus coverage keyed by public office code (WIPO ST.3, e.g. US, EM): freshness watermark (as_of, ISO ts | null) and coverage status. Covers the offices that GATED this verdict — the requested offices (offices-scoped), the national + regional/member registers (jurisdictions-scoped), or every live office (unscoped). Empty only when the coverage registry could not be read."},"index_generation":{"type":["integer","null"],"description":"Generation of the search index the candidates were retrieved from (the same value as `search_meta.index_generation` on trademark search); null when it could not be read. Part of `screening_id`: a rebuilt index is a different decision input.","example":4}},"required":["rules","scorer","strength","litigation","semantics","assets","lane_plan","catalog","coverage_registry","cache_shape","corpus_watermarks","index_generation"],"description":"Version receipt: rules/scorer/semantics/assets/lane-plan/catalog/coverage-registry/cache-shape versions plus per-office corpus watermarks. Version strings only; never scores/probabilities."},"ScreeningMeta":{"type":"object","properties":{"verdict":{"type":"string","enum":["high_risk","caution","needs_review","clear"],"description":"Derived from band counts and coverage. \"needs_review\" is emitted when a would-be \"clear\" cannot be confirmed: incomplete protection-scope coverage (a requested territory's register is dark; see `coverage`), a mark in an unsupported script (`coverage.language.supported: false`), or (flip-gated) model-borderline evidence. Found conflicts always band high/medium regardless of coverage."},"summary":{"type":"object","properties":{"high":{"type":"integer"},"medium":{"type":"integer"},"low":{"type":"integer"},"truncated":{"type":"boolean"}},"required":["high","medium","low","truncated"]},"litigation_risk":{"type":"object","properties":{"high":{"type":"integer"},"medium":{"type":"integer"}},"required":["high","medium"],"description":"How many surfaced conflicts are owned by formidable (litigation-risk high/medium) parties — a separate axis from the conflict verdict."},"candidate":{"type":"object","properties":{"mark":{"type":"string","example":"KOFEE"},"normalized":{"type":"string","description":"Mark-text fold (lowercase/trim/Unicode-fold).","example":"kofee"},"trademark_id":{"type":"string","description":"Present when the candidate was sourced from an existing register record.","example":"tm_0190f2d5-8e4b-7c1a-a8d3-123456789abc"}},"required":["mark","normalized"]},"screening_id":{"type":"string","description":"Deterministic, version-prefixed receipt id (SHA-256 of the recorded decision inputs). Two semantically-equivalent requests share an id; any decision-input change (office/class/as-of/watermark/version, including retrieval-profile content and index/analyzer generation) changes it. Excludes request id, timestamps, latency, cache-hit, and page order. NO stored snapshot - replay recomputes identity from the recorded inputs.","example":"scr1_9f2c..."},"inferred_nice_classes":{"type":"array","items":{"type":"integer"},"description":"Nice classes inferred from goods_services when nice_classes was omitted. Present only when inference ran; these are the effective classes used for retrieval/banding.","example":[9,42]},"rules_version":{"type":"string","description":"The ScreeningStrategy id that produced this response (e.g. screening-v1).","example":"screening-v1"},"band_source":{"type":"string","enum":["v1_table","v3_scorer"],"description":"Origin of the served verdict/band: \"v1_table\" with the v1 band table (default) or \"v3_scorer\" when the v3 scorer strategy is active. Informational."},"versions":{"$ref":"#/components/schemas/ScreeningVersions"},"resolver":{"type":"object","properties":{"engine_version":{"type":"string","example":"use-resolver-v0-stub"},"ruleset_version":{"type":"string","example":"none"},"catalog_version":{"type":"string","example":"none"}},"required":["engine_version","ruleset_version","catalog_version"],"description":"Goods/services resolver version triple that produced this coverage. A resolver upgrade (relatedness engine / ruleset / catalog) is visible here — results can change even when rules_version is unchanged."},"resolution":{"type":"object","properties":{"mode_requested":{"type":"string","enum":["auto","deterministic","llm"],"description":"The resolution_mode the request asked for."},"method":{"type":"string","enum":["deterministic","semantic","llm","llm_cached"],"description":"Deepest cascade lane that actually contributed to this coverage (the billing + debugging key). \"llm\"/\"llm_cached\" are reserved for tier-3 and not emitted yet. Per-area basis_codes carry the fine-grained provenance."},"top_semantic_score_q":{"type":["integer","null"],"description":"Top-1 semantic retrieval score (quantized scale) across the semantic areas that contributed; null when method is not \"semantic\"."},"llm_model":{"type":["string","null"],"description":"BETA (tier-3) — the pinned model revision that produced a billed LLM adjudication (method \"llm\"/\"llm_cached\"), so a customer can verify which model they paid for. null on the deterministic/semantic path."},"cache":{"type":["string","null"],"enum":["hit","miss",null],"description":"BETA (tier-3) — cache disposition of an LLM adjudication: \"hit\" (replayed, billed llm_cached), \"miss\" (a model call ran, billed llm), or null (no LLM lane / honest fallback)."},"areas":{"type":"array","items":{"type":"object","properties":{"nice_class":{"type":"integer","example":25},"label":{"type":"string","example":"Clothing"},"role":{"type":"string","enum":["core","related","adjacent","conditional","administrative"],"description":"The coverage role of this area within the resolution."},"method":{"type":"string","enum":["deterministic","semantic","llm"],"description":"WHICH LANE produced this area (provenance only, NOT a certainty claim): \"deterministic\" = exact/edge/rule/class-fallback; \"semantic\" = retrieved by the semantic lane; \"llm\" = selected/confirmed by the tier-3 LLM adjudicator (always \"suggested\"). A deterministic area can still be uncertain — see \"suggested\"."},"suggested":{"type":"boolean","description":"WHETHER THE CALLER SHOULD VERIFY before relying on this area (an uncertainty axis, independent of \"method\"). true when the area is semantic-derived, OR its confidence is below \"high\", OR its provenance is a low-certainty deterministic source (e.g. class_fallback). Only a high-confidence grounded deterministic area is false (a certain class)."},"confidence":{"type":"string","enum":["high","medium","low"],"description":"Area confidence. Semantic-derived areas are capped at medium; a below-high confidence sets suggested=true regardless of lane."},"basis_codes":{"type":"array","items":{"type":"string"},"description":"Machine-readable per-area provenance codes explaining WHY the area was included (and why it is / is not suggested), e.g. [\"semantic_match\"], [\"class_fallback\"], [\"request_class\"].","example":["semantic_match"]},"score_q":{"type":["integer","null"],"description":"Semantic retrieval score (quantized scale) for a semantic area; null on deterministic areas."}},"required":["nice_class","label","role","method","suggested","confidence","basis_codes","score_q"]},"description":"Per-area suggestion marking (TUR P1d). Every resolved coverage area flagged as a certain class (\"deterministic\") or a lower-confidence suggestion (\"semantic\"/suggested:true), so a consumer can render a suggestion distinctly from a confident class."}},"required":["mode_requested","method","top_semantic_score_q","llm_model","cache","areas"],"description":"BETA — present only when the cascade-modes flag is enabled. Request-level rollup of how the goods/services coverage was resolved (mode requested, deepest method that fired, top semantic score, and per-area suggestion marking)."},"as_of":{"type":["string","null"],"description":"Corpus freshness watermark. null when unknown."},"admitted_match_levels":{"type":"array","items":{"type":"string"},"example":["exact","normalized","fuzzy_1","phonetic_strong"]},"note":{"type":"string","description":"Present on verdict:\"clear\" (clear ≠ registrable) and on a coverage-gated \"needs_review\" (explains which territories' national registers are dark)."},"coverage":{"allOf":[{"$ref":"#/components/schemas/ScreeningCoverage"},{"description":"Per-territory + office protection-scope coverage. Present whenever the coverage registry was readable. `complete_for_clear:false` is why an otherwise-clear verdict was downgraded to needs_review."}]},"warnings":{"type":"array","items":{"type":"string"},"example":["no_goods_services"]}},"required":["verdict","summary","litigation_risk","candidate","screening_id","rules_version","versions","resolver","as_of","admitted_match_levels","warnings"]},"ScreeningResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"screening":{"$ref":"#/components/schemas/ScreeningMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningHit"}},"has_more":{"type":"boolean","enum":[false]},"pagination":{"type":"object","properties":{"cursor":{"type":"null"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","screening","data","has_more","pagination"]},"CompareMeta":{"type":"object","properties":{"candidate":{"type":"object","properties":{"trademark_id":{"type":"string"},"mark":{"type":"string"},"normalized":{"type":"string"},"effective_nice_classes":{"type":"array","items":{"type":"integer"}}},"required":["mark","normalized","effective_nice_classes"]},"rules_version":{"type":"string","enum":["compare-v1.1"]},"band_rules_version":{"type":"string"},"mapping_version":{"type":"string"},"resolver":{"type":"object","properties":{"engine_version":{"type":"string"},"ruleset_version":{"type":"string"},"catalog_version":{"type":"string"}},"required":["engine_version","ruleset_version","catalog_version"]},"as_of":{"type":["string","null"]},"warnings":{"type":"array","items":{"type":"string"},"description":"Open vocabulary; consumers must tolerate warnings added in future."},"disclaimer":{"type":"string"}},"required":["candidate","rules_version","band_rules_version","mapping_version","resolver","as_of","warnings","disclaimer"]},"ComparisonResult":{"type":"object","properties":{"object":{"type":"string","enum":["comparison_result"]},"comparison_status":{"type":"string","enum":["ok","not_found","not_comparable"],"description":"Closed vocabulary; consumers may exhaustively switch on these values."},"review_recommended":{"type":"boolean","description":"True exactly when comparison_status is `ok` and at least one mark-similarity clause fired. This conservative human-review signal includes dead-mark and below-screening-band pairs and is independent of risk_level."},"conflict":{"type":"object","properties":{"trademark_id":{"type":"string"},"mark":{"type":["string","null"]},"nice_classes":{"type":["array","null"],"items":{"type":"integer"}},"status_as_evaluated":{"type":["string","null"]},"record_as_of":{"type":["string","null"]}},"required":["mark","nice_classes","status_as_evaluated","record_as_of"]},"warnings":{"type":"array","items":{"type":"string"},"description":"Open vocabulary; consumers must tolerate warnings added in future."},"risk_level":{"type":["string","null"],"enum":["high","medium","low",null],"description":"Closed vocabulary; consumers may exhaustively switch on these values."},"reason_codes":{"type":["array","null"],"items":{"type":"string"},"description":"Open vocabulary; consumers must tolerate reason codes added in future."},"mark_match":{"type":["object","null"],"properties":{"level":{"type":"string","enum":["identical","strong","weak","none"],"description":"Closed vocabulary; consumers may exhaustively switch on these values."},"matched_levels":{"type":"array","items":{"type":"string"},"description":"Engine clauses matched for this pair. This is named `matched_levels` because Compare has no sensitivity admission gate; Screening's corresponding post-gate field is `admitted_match_levels`."}},"required":["level","matched_levels"]},"goods_services":{"type":["object","null"],"properties":{"level":{"type":"string","enum":["same_class","related_class","unrelated"],"description":"Closed vocabulary; consumers may exhaustively switch on these values."},"overlap_classes":{"type":"array","items":{"type":"integer"}},"text_similarity":{"type":["number","null"],"minimum":0,"maximum":1}},"required":["level","overlap_classes","text_similarity"]},"similarity":{"type":["object","null"],"properties":{"string":{"type":"number","minimum":0,"maximum":1},"phonetic":{"type":"number","minimum":0,"maximum":1},"semantic":{"type":"null","description":"Reserved for a future semantic dimension."}},"required":["string","phonetic","semantic"]}},"required":["object","comparison_status","review_recommended","conflict","warnings","risk_level","reason_codes","mark_match","goods_services","similarity"]},"CompareResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"comparison":{"$ref":"#/components/schemas/CompareMeta"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ComparisonResult"}},"summary":{"type":"object","properties":{"high":{"type":"integer"},"medium":{"type":"integer"},"low":{"type":"integer"},"none":{"type":"integer"},"not_comparable":{"type":"integer"},"review_recommended":{"type":"integer","description":"Number of results where comparison_status is `ok` and at least one mark-similarity clause fired, independent of risk_level."}},"required":["high","medium","low","none","not_comparable","review_recommended"]},"has_more":{"type":"boolean","enum":[false]},"pagination":{"type":"object","properties":{"cursor":{"type":"null"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","comparison","data","summary","has_more","pagination","request_id"]},"TrademarkUseProfile":{"type":"object","properties":{"nice_classes":{"type":"array","items":{"type":"integer","minimum":1,"maximum":45},"description":"Intended Nice class numbers (1-45).","example":[30,43]},"goods_services":{"type":"array","items":{"type":"object","properties":{"nice_class":{"type":"integer","minimum":1,"maximum":45},"text":{"type":"string","maxLength":500}},"required":["text"],"additionalProperties":false},"description":"Structured goods/services lines, each optionally pinned to a Nice class."},"business_description":{"type":"string","maxLength":2000,"description":"Free-text description of the business / intended use.","example":"Roasting and retail sale of specialty coffee beans."}},"additionalProperties":false,"description":"A structured, mark-INDEPENDENT view of the customer's intended goods/services. The canonical resolver input shared by screening and compare."},"CompareRequest":{"type":"object","properties":{"candidate":{"anyOf":[{"type":"object","properties":{"trademark_id":{"type":"string"}},"required":["trademark_id"],"additionalProperties":false},{"type":"object","properties":{"mark":{"type":"string","maxLength":200},"use":{"$ref":"#/components/schemas/TrademarkUseProfile"}},"required":["mark","use"],"additionalProperties":false}]},"conflicts":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"trademark_id":{"type":"string"}},"required":["trademark_id"],"additionalProperties":false},{"type":"object","properties":{"mark":{"type":"string","maxLength":200},"nice_classes":{"type":"array","items":{"type":"integer","minimum":1,"maximum":45},"minItems":1},"goods_services":{"type":"string","maxLength":2000},"status":{"type":"string","enum":["active","pending","inactive","unknown"],"default":"unknown"}},"required":["mark","nice_classes"],"additionalProperties":false}]},"minItems":1},"jurisdictions":{"type":"array","items":{"type":"string"},"maxItems":30},"offices":{"type":"array","items":{"type":"string"},"maxItems":30}},"required":["candidate","conflicts"],"additionalProperties":false},"ListingMeta":{"type":"object","properties":{"verdict":{"type":"string","enum":["clear","caution","high_risk"],"description":"Worst verdict over screened candidates (never clear when the candidate budget was capped). Retained for back-compat; clients should read auto_approve_eligible and analysis_status, not this tri-state verdict alone."},"action":{"type":"string","enum":["approve","approve_monitor","review","block"],"description":"DERIVED 4-tier moderation action — the recommended handling of this listing. A pure projection of verdict/lanes/analysis_status; verdict semantics are unchanged. STRUCTURAL SAFETY: high_risk maps ONLY to block|review, caution ONLY to approve_monitor|review, clear ONLY to approve|review (a high_risk listing can never auto-approve; a clear can never block). block = high_risk driven by a counterfeit / evasion / unauthorized-merch escalation or the persona/character/franchise lane. review = incomplete/unscreenable/unsupported listings, any other high_risk, or a caution whose hold is not a proven-benign residual. approve_monitor = a COMPLETE caution whose every hold is a benign residual (famous-in-title caution / numeric-SKU probe hit). approve = clear AND analysis_status complete (equivalent to auto_approve_eligible). A brand self-match caution is NOT approve_monitor: without a seller-verification attestation it is indistinguishable from a third-party collision, so it is `review` with reason `selfmatch_flag_off` (ENG-22 W5); WITH a covering attestation it demotes and the listing becomes `approve`."},"action_reasons":{"type":"array","items":{"type":"string","enum":["clear_complete","counterfeit_signal","evasion_signal","unauthorized_merch_escalation","persona_ip_escalation","actionable_hit","analysis_incomplete","unscreenable","unsupported_language","famous_in_title_band_derived","numeric_probe_hit","selfmatch_flag_off"]},"description":"DERIVED closed audit reasons behind `action`. Each grounds in real machinery. block: counterfeit_signal (counterfeit_misuse escalation), evasion_signal (evasion_fold_admission escalation), unauthorized_merch_escalation (famous_reference_merch escalation), persona_ip_escalation (persona/character/franchise high). review: actionable_hit (a non-block high or a caution with an actionable hold), analysis_incomplete (analysis could not complete — budget/timeout/backend/variant-shed/stale-snapshot), unscreenable (an admitted candidate could not be screened), unsupported_language (non-English listing). approve_monitor: famous_in_title_band_derived (a famous mark capped to caution), numeric_probe_hit (a numeric-SKU brand that probe-hit the register and banded caution). approve: clear_complete. review (informative): selfmatch_flag_off (ENG-22 W5 — a caution whose ONLY hold is a brand self-match that WOULD have demoted had the seller-verification attestation been present and covered the mark; stays review because an unverified self-match cannot be distinguished from a third-party collision)."},"summary":{"type":"object","properties":{"high":{"type":"integer"},"medium":{"type":"integer"},"low":{"type":"integer"},"informational":{"type":"integer"}},"required":["high","medium","low","informational"]},"candidates_screened":{"type":"integer","description":"How many extracted candidates were fanned out to the screening core."},"rules_version":{"type":"string","enum":["screening-v1"]},"verdict_version":{"type":"string","enum":["listing-verdict-v30"]},"extractor_version":{"type":"string","description":"Content-hash of the deterministic extractor + dictionaries."},"selector_version":{"type":"string","description":"Content-hash of the index-driven candidate-selection contract (ENG-22 v2)."},"as_of":{"type":["string","null"],"description":"Corpus freshness watermark. null when unknown."},"warnings":{"type":"array","items":{"type":"string"},"example":["candidate_budget_capped","incomplete_office_coverage"]},"note":{"type":"string","description":"Present on verdict:\"clear\" — clear ≠ registrable."},"analysis_status":{"type":"string","enum":["complete","incomplete_budget","incomplete_timeout","incomplete_backend","incomplete_unscreenable","incomplete_variant_shed","incomplete_stale_snapshot","unsupported_language"],"description":"Closed enum, ORTHOGONAL to verdict. Derived deterministically from analysis-completeness signals; complete means the listing was fully screened. incomplete_timeout/incomplete_backend are reserved (503 today)."},"auto_approve_eligible":{"type":"boolean","description":"true ONLY when verdict===\"clear\" AND analysis_status===\"complete\". Incomplete is never auto-approvable. Read this (with analysis_status), not verdict alone."},"class_provenance":{"type":"object","properties":{"source":{"type":"string","enum":["provided_platform","provided_unverified","inferred","none"]},"confidence":{"type":["number","null"]}},"required":["source","confidence"],"description":"Where the screened Nice classes came from. provided_unverified = caller-supplied, not verified against a platform taxonomy."},"resolved_nice_classes":{"type":"array","items":{"type":"integer"},"description":"Listing-level Nice classes resolved from caller input or category inference. Inferred classes are reported for transparency and do not affect verdict gates."},"dictionaries_version":{"type":"string"},"decision_asset_version":{"type":"string","description":"Cheap content hash over the decision-asset version tuple (verdict+extractor+selector+dictionaries+persona bank+category map)."},"forms_evaluated":{"type":"integer","description":"Fan-out forms actually evaluated. Present (together with forms_total) whenever variant shedding occurred, independent of the headline analysis_status — variant shedding can co-occur with a higher-priority status (e.g. incomplete_budget / unsupported_language / incomplete_unscreenable), so these counters are not gated on analysis_status===\"incomplete_variant_shed\"."},"forms_total":{"type":"integer"}},"required":["verdict","summary","candidates_screened","rules_version","verdict_version","extractor_version","selector_version","as_of","warnings","analysis_status","auto_approve_eligible","class_provenance","resolved_nice_classes","dictionaries_version","decision_asset_version"]},"ListingScreeningHit":{"allOf":[{"$ref":"#/components/schemas/ScreeningHit"},{"type":"object","properties":{"informational":{"type":"boolean","description":"Surfaced but non-escalating due to unrelated class or listing distinctiveness calibration."},"informational_reason":{"type":"string","enum":["unrelated_class_identical","generic_term_no_corroboration","crowded_field_no_corroboration","identical_unrelated_no_corroboration","nominative_compat"],"description":"Closed audit reason explaining why this conflict is informational."}}}],"description":"Registration evidence — byte-identical to the matching data[].hits[] entry (same informational flag + reason)."},"ListingMatch":{"oneOf":[{"type":"object","properties":{"object":{"type":"string","enum":["listing_match"]},"source":{"type":"string","enum":["live_register"]},"disposition":{"type":"string","enum":["actionable","informational"]},"reason_codes":{"type":"array","items":{"type":"string"}},"rights_domain":{"type":"string","enum":["trademark"],"description":"Live-register trademark match (source:\"live_register\")."},"goods_services_text_available":{"type":"boolean"},"candidate":{"type":"object","properties":{"term":{"type":"string"},"normalized":{"type":"string"},"tier":{"type":"string","enum":["P","S"]},"field":{"type":"string","enum":["title","brand","description","keywords"]}},"required":["term","normalized","tier","field"]},"registration":{"$ref":"#/components/schemas/ListingScreeningHit"}},"required":["object","source","disposition","reason_codes","rights_domain","goods_services_text_available","candidate","registration"]},{"type":"object","properties":{"object":{"type":"string","enum":["listing_match"]},"source":{"type":"string","enum":["curated_bank"]},"disposition":{"type":"string","enum":["actionable","informational"]},"reason_codes":{"type":"array","items":{"type":"string"}},"rights_domain":{"type":"string","enum":["character_ip","persona_publicity","franchise"],"description":"Curated non-register persona/character right (source:\"curated_bank\"). NOT a live-register lookup — merch-context corroborated; policy-toggleable independently of trademark verdicts."},"goods_services_text_available":{"type":"boolean"},"candidate":{"type":"object","properties":{"term":{"type":"string"},"normalized":{"type":"string"},"tier":{"type":"string","enum":["P","S"]},"field":{"type":"string","enum":["title","brand","description","keywords"]}},"required":["term","normalized","tier","field"]},"bank_entry":{"type":"object","properties":{"canonical":{"type":"string"},"review_date":{"type":"string"},"note":{"type":"string"}},"required":["canonical","review_date","note"],"description":"Curated bank provenance — canonical name + review date. Honest labeling."}},"required":["object","source","disposition","reason_codes","rights_domain","goods_services_text_available","candidate","bank_entry"]}]},"ListingCandidate":{"type":"object","properties":{"object":{"type":"string","enum":["listing_candidate"]},"term":{"type":"string","example":"AirPods"},"normalized":{"type":"string","example":"airpods"},"tier":{"type":"string","enum":["P","S"],"description":"Fan-out lane: P = brand/reference (full clauses), S = title/keyword (strict)."},"reference":{"type":"boolean","description":"Nominative-use reference (\"compatible with X\") — never a sole high-risk driver."},"reference_intent":{"type":"string","enum":["compat","attribution","prose"],"description":"Advisory reference framing for this candidate. 'compat' covers BOTH reference-grade fitment frames (\"for <Mark> <model>\") and demotion-grade explicit connectors (\"compatible with <Mark>\", \"<Mark>-compatible\") — it does NOT imply nominative-safe use or that the nominative-compat demotion applied (an internal, occurrence-local eligibility check governs that). Never a sole risk/safety driver."},"counterfeit":{"type":"boolean","description":"Counterfeit-signal language (\"replica\"/\"knockoff\"/\"dupe\"/\"inspired by X\") near this mark (ENG-156) — can drive high_risk even for a reference candidate."},"sources":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["title","brand","description","keywords"]},"span":{"type":"array","prefixItems":[{"type":"integer"},{"type":"integer"}],"description":"[start, end) char offsets into the source field."},"keyword_index":{"type":"integer"}},"required":["field","span"]},"description":"Where this candidate appears in the listing (provenance)."},"verdict":{"type":"string","enum":["clear","caution","high_risk"],"description":"Effective candidate verdict (after the informational-only adjustment)."},"nice_classes_used":{"type":"array","items":{"type":"integer"}},"hits":{"type":"array","items":{"$ref":"#/components/schemas/ListingScreeningHit"},"description":"Up to 5 conflicts, byte-identical to a GET /v1/screening hit (+ an informational flag)."},"confidence":{"type":"string","enum":["high","medium","low"],"description":"DERIVED confidence that THIS candidate is a real conflict — a deterministic projection of the candidate's effective verdict + authoritative band summary (NOT a new model). high = the candidate is high_risk; medium = caution WITH actionable band evidence (a high/medium band it carries, e.g. a reference-clamped/capped high or a real medium); low = clear, or a caution floored without actionable band support (informational-only / probe-conflict / listing floor)."},"rank":{"type":"integer","description":"DERIVED review-tier severity rank of this candidate within the listing (0 = most severe). Candidates are ordered by (verdict severity, then high/medium/low band counts), ties broken by candidate order. Additive; does not reorder data[]."}},"required":["object","term","normalized","tier","sources","verdict","nice_classes_used","hits"]},"SuppressedCandidate":{"type":"object","properties":{"object":{"type":"string","enum":["suppressed_candidate"]},"term":{"type":"string"},"normalized":{"type":"string"},"field":{"type":"string","enum":["title","brand","description","keywords"]},"span":{"type":"array","prefixItems":[{"type":"integer"},{"type":"integer"}]},"keyword_index":{"type":"integer"},"reason":{"type":"string","enum":["charset","stopword","jargon","descriptive","generic_term","no_index_hit","containment","cap","protected_cap","numeric_id_brand","unscreenable"],"description":"Closed reason code for why this candidate was NOT screened (auditability). `generic_term` = a single common-word gram suppressed before probing (never screened; equivalent to a generic demotion, done early for latency). `no_index_hit` = the mark index returned no exact/normalized match (index-driven selection, ENG-22 v2). `protected_cap` = the protected-bank fan-out ceiling overflowed. `numeric_id_brand` = a digit-dominant SKU-shaped brand string (marketplace SKU/model number) that returned no live exact/normalized registration when probe-gated against the index — treated as data noise, verdict title-determined (a numeric brand that DOES match a registration is screened normally; known numeric marks and counterfeit-bearing listings always screen). `unscreenable` = an admitted candidate whose query tripped the plain-text validator (ENG-157) — the listing is still floored to caution."}},"required":["object","term","normalized","field","span","reason"]},"ListingCheckResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"listing":{"$ref":"#/components/schemas/ListingMeta"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/ListingMatch"},"description":"Evidence-first primary payload: one entry per matched mark (deduped, attributed). Leads with disposition + reason codes + registration evidence."},"data":{"type":"array","items":{"$ref":"#/components/schemas/ListingCandidate"}},"suppressed":{"type":"array","items":{"$ref":"#/components/schemas/SuppressedCandidate"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","listing","matches","data","suppressed","has_more","pagination"]},"ListingCheckBody":{"type":"object","properties":{"title":{"type":"string","minLength":2,"maxLength":500,"description":"Listing title (REQUIRED). Split on hard delimiters, then n-grammed."},"brand":{"type":"string","minLength":1,"maxLength":2000,"description":"Explicit brand/seller name. Screened as a brand candidate. A digit-dominant SKU-shaped string (\"1806\", \"894\") is probe-gated against the register: if it matches a live registration it is screened normally; otherwise it is treated as data noise and reported under `suppressed[]` with reason `numeric_id_brand` (known numeric marks and counterfeit-bearing listings always screen)."},"description":{"type":"string","maxLength":10000,"description":"Listing description. High-precision markers only (quoted / ™®-adjacent / \"compatible with X\")."},"keywords":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":64,"description":"Platform-neutral tags/keywords/search terms. Each is a pre-segmented candidate."},"category":{"type":"string","maxLength":200,"description":"Listing category/taxonomy label. Context only — never itself a candidate."},"nice_classes":{"type":"array","items":{"type":"integer","minimum":1,"maximum":45},"maxItems":45,"description":"Intended Nice class numbers (hard filter + class-conditioned descriptive suppression)."},"jurisdictions":{"type":"array","items":{"type":"string","minLength":2,"maxLength":16},"maxItems":64,"description":"Restrict to these jurisdiction (territory) codes (UK is read as GB, WIPO as WO). Default: all live-coverage jurisdictions."},"offices":{"type":"array","items":{"type":"string","minLength":2,"maxLength":16},"maxItems":64,"description":"Restrict to these registering office codes (WIPO ST.3, e.g. US, EM; legacy internal codes accepted). Default: all live offices."},"include":{"type":"string","enum":["live","all"],"default":"live","description":"live (default) keeps live marks; all includes dead."},"sensitivity":{"type":"string","enum":["strict","standard","broad"],"default":"standard","description":"Band-admission threshold for the primary (brand/reference) tier. The title/keyword tier is always screened at strict."},"seller_verification":{"type":"object","properties":{"brand_owner_verified":{"type":"boolean","description":"The caller ATTESTS the seller is verified as the owner of the listing brand. Signa treats this as a trust INPUT — it does NOT verify ownership itself; the caller carries the liability for a wrong attestation. When true, an EXACT brand self-match (the listing brand identically matching a live registration in an unrelated/unknown class) may demote to clear under LIVE guards: the mark must be attestation-covered, the analysis must be complete, there must be no title-side actionable hit on a different mark, and any counterfeit/evasion signal or famous mark ALWAYS keeps full screening (attestation is not immunity). false/absent ⇒ inert."},"verified_marks":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"minItems":1,"maxItems":64,"description":"Optional explicit list of mark texts the seller is verified to own. When PRESENT it is ALWAYS strict membership: the self-match demotion applies ONLY to a matched mark whose normalized (folded) form is in this list. Compare against the register mark surface — punctuation/spacing differences fold together (\"Kate Spade\" ⇄ \"kate spade\") but a fundamentally different surface fails closed. When ABSENT, the attestation covers the listing brand only (any NON-famous brand-field mark); famous marks ALWAYS require explicit enumeration here (and are still never cleared — a famous mark is inherently review-worthy). An empty array, empty/symbol-only strings, or non-strings are rejected (400) — never partially honored."}},"required":["brand_owner_verified"],"additionalProperties":false,"description":"Per-request seller-verification trust context (additive; absent ⇒ verdict/lane/action-value identical to today). Replaces the global self-match demote flag with a per-request entitlement so a verified brand owner is distinguished from an infringer using someone else brand. Attest ONLY when the seller has actually been verified as owner of the covered marks — a blanket/unconditional attestation misuses this field and shifts the false-clear liability to the caller."}},"required":["title"],"additionalProperties":false},"ScreeningBatchSubmit":{"type":"object","properties":{"object":{"type":"string","enum":["screening_batch"]},"id":{"type":"string","example":"scb_1f2e3d4c-5b6a-7089-90ab-cdef01234567"},"status":{"type":"string","enum":["queued"]},"item_count":{"type":"integer"},"status_url":{"type":"string","description":"Poll this URL for job status + results. NOTE: an idempotent replay (retry with the same Idempotency-Key) omits the Location header — this body field is the authoritative poll URL."},"created_at":{"type":"string"},"updated_at":{"type":"string","description":"Last status-transition timestamp."},"expires_at":{"type":"string","description":"When the job + results are purged (fixed at creation; TTL does not slide)."},"request_id":{"type":"string"}},"required":["object","id","status","item_count","status_url","created_at","updated_at","expires_at"]},"ScreeningBatchBody":{"type":"object","properties":{"listings":{"type":"array","items":{"$ref":"#/components/schemas/ListingCheckBody"},"minItems":1,"maxItems":100,"description":"1–100 listing-check requests. Each item is the exact POST /v1/screening/listings body (incl. seller_verification). Screened asynchronously with bounded concurrency; poll the returned job for results. VALIDATION POLICY: every item must be schema-valid — a single schema-invalid item rejects the WHOLE request with a 400 (Stripe-style, so a malformed submission never silently drops rows). SEMANTIC failures (bad office/jurisdiction code, backend 503, over-long brand) are isolated PER ITEM at execution as an item-level error, never failing the job. SIZE: the request must fit the global body cap (~256 KiB) — a larger payload is rejected with 413; keep batches modest (fewer/smaller listings) well under both that cap and the 16 MiB result-storage ceiling."}},"required":["listings"],"additionalProperties":false},"ScreeningBatchItemError":{"type":"object","properties":{"type":{"type":"string","description":"snake_case error slug (e.g. validation_error)."},"title":{"type":"string"},"detail":{"type":"string"},"status":{"type":"integer"},"retryable":{"type":"boolean","description":"Whether retrying the SAME item may succeed."},"retry_after":{"type":["integer","null"],"description":"Seconds to wait before retry, when applicable."},"suggestion":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["field","code","message"]},"description":"Per-field issues — present only on 400 validation errors."}},"required":["type","title","detail","status","retryable","retry_after"],"description":"Job-level error (only on status=failed, e.g. storage_limit_exceeded)."},"ScreeningBatchItemResult":{"type":"object","properties":{"index":{"type":"integer","description":"Zero-based position in the submitted `listings[]`."},"status":{"type":"string","enum":["completed","failed"]},"result":{"allOf":[{"$ref":"#/components/schemas/ListingCheckResponse"},{"description":"Present when status=completed — identical (values + key order) to the sync POST /v1/screening/listings body modulo request_id."}]},"error":{"allOf":[{"$ref":"#/components/schemas/ScreeningBatchItemError"},{"description":"Present when status=failed — an item-level error; other items are unaffected."}]}},"required":["index","status"]},"ScreeningBatchStatus":{"type":"object","properties":{"object":{"type":"string","enum":["screening_batch"]},"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","partial","failed"]},"item_count":{"type":"integer"},"completed_count":{"type":"integer"},"failed_count":{"type":"integer"},"created_at":{"type":"string"},"updated_at":{"type":"string","description":"Last status-transition timestamp. STALENESS: a job stuck in `running` with an `updated_at` far in the past (roughly > LISTING_DEADLINE × item_count / concurrency + margin) was likely abandoned when its owning process died (execution is at-most-once, no retry) — resubmit."},"expires_at":{"type":"string"},"error":{"$ref":"#/components/schemas/ScreeningBatchItemError"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ScreeningBatchItemResult"},"description":"Per-item results in submission order — present when status ∈ {completed, partial}."},"request_id":{"type":"string"}},"required":["object","id","status","item_count","completed_count","failed_count","created_at","updated_at","expires_at"]},"Portfolio":{"type":"object","properties":{"id":{"type":"string","example":"ptf_abc123"},"object":{"type":"string","enum":["portfolio"]},"name":{"type":"string"},"description":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"trademark_count":{"type":"integer"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"request_id":{"type":"string"}},"required":["id","object","name","description","metadata","trademark_count","created_at","updated_at","request_id"]},"PortfolioList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ptf_abc123"},"object":{"type":"string","enum":["portfolio"]},"name":{"type":"string"},"description":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"trademark_count":{"type":"integer"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","description","metadata","trademark_count","created_at","updated_at"]}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"PortfolioMark":{"allOf":[{"$ref":"#/components/schemas/TrademarkSummaryV1"},{"type":"object","properties":{"added_at":{"type":"string","description":"When this trademark was added to the portfolio (RFC 3339).","example":"2026-03-18T04:00:00Z"},"added_by":{"type":["string","null"],"description":"API key that added the membership, or null when it predates attribution.","example":"key_abc123"},"external_ref":{"type":["string","null"],"description":"The caller's own docketing reference for THIS membership, or null when none is bound. Membership metadata, not trademark data: the same mark in two portfolios can carry two different references, or none.","example":"ACME-2024-001"}},"required":["added_at","added_by","external_ref"]}]},"PortfolioMarkList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PortfolioMark"}},"has_more":{"type":"boolean","description":"Whether more memberships exist beyond this page. Under `limit=0` with no filter this is read from the cached trademark_count; under `limit=0` WITH a filter it reports whether the filter matched."},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]}},"required":["cursor"]}},"required":["object","data","has_more","pagination"]},"PortfolioDetail":{"allOf":[{"$ref":"#/components/schemas/Portfolio"},{"type":"object","properties":{"trademarks":{"$ref":"#/components/schemas/PortfolioMarkList"}},"required":["trademarks"]}]},"AlertDiffEntry":{"type":"object","properties":{"path":{"type":"string","description":"Underlying flat change-tracking field token (e.g. `status_primary`). Intentionally differs from the nested `trademark` object keys (e.g. `status.primary`); treat as an opaque field identifier."},"op":{"type":"string","enum":["set","unset","changed"]},"from":{},"to":{}},"required":["path","op"]},"AlertTrademark":{"type":"object","properties":{"id":{"type":"string","example":"tm_01HK..."},"mark_text":{"type":["string","null"]},"mark_feature_type":{"type":["string","null"]},"office_code":{"type":["string","null"],"description":"WIPO ST.3 office code (uppercase, e.g. `US`, `EM`). Null when the stored snapshot value cannot be translated to the public vocabulary (fail-closed).","example":"US"},"status":{"type":"object","properties":{"primary":{"type":"string"},"stage":{"type":"string"}},"required":["primary","stage"]},"filing_date":{"type":["string","null"]},"registration_date":{"type":["string","null"]},"nice_classes":{"type":"array","items":{"type":"integer"}},"owner_name":{"type":["string","null"]},"as_of":{"type":["string","null"],"description":"When the source change occurred (source_occurred_at). Null on pre-v2 alerts."},"links":{"type":"object","properties":{"self":{"type":"string"}},"required":["self"]}},"required":["id","as_of","links"]},"AlertList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"alt_01HK..."},"object":{"type":"string","enum":["alert"]},"schema_version":{"type":"string","enum":["2026-06-01"]},"watch":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["mark","portfolio","owner","class","similarity"]}},"required":["id","name","type"]},"customer_reference":{"type":["string","null"],"description":"Customer passthrough set on the watch; null if unset."},"event":{"type":"object","properties":{"type":{"type":"string","enum":["trademark.created","trademark.updated","trademark.status_changed","trademark.retracted","trademark.corrected"]},"summary":{"type":"string","description":"Short human-readable description, e.g. \"Status changed: pending → registered\"."},"diff":{"type":"array","items":{"$ref":"#/components/schemas/AlertDiffEntry"},"description":"Field-level change diff. Entry `path` values are the underlying flat change-tracking field tokens (e.g. `status_primary`) and intentionally differ from the nested `trademark` object keys (e.g. `status.primary`); treat them as opaque field identifiers."},"diff_truncated":{"type":"boolean","description":"Present and `true` when the change diff was bounded (entries dropped past the max count, or an over-long from/to value replaced with a sentinel, or a byte-budget cap hit). Absent when the diff is complete."}},"required":["type","summary","diff"]},"match":{"type":["object","null"],"properties":{"reason":{"type":["string","null"]},"score":{"type":["number","null"]},"score_basis":{"type":["string","null"]},"tier":{"type":["string","null"],"enum":["identical","near_identical","similar","related",null],"description":"Similarity tier of the matched mark, the same label a search hit carries as `match.tier` (identical, near_identical, similar, related). A retrieval category, not a measured edit distance. Null for filter-only watches, marks found only by their number, and alerts emitted before the field existed."}},"required":["reason","score","score_basis","tier"],"description":"Match metadata (why/how the mark matched the watch). Null for pure-filter / pre-v2 alerts that carry no match scoring. `score` is the engine score for the watch query, not the 0-100 search `relevance_score`."},"trademark":{"$ref":"#/components/schemas/AlertTrademark"},"deadline":{"type":"object","properties":{"severity":{"type":"string","enum":["normal","high","critical"]},"opposition_window_status":{"type":["string","null"],"enum":["open","closing_soon","critical","closed",null]},"must_act_by":{"type":["string","null"]},"must_act_by_adjustment":{"type":["string","null"],"enum":["moved","unchanged","not_checked","month_end_overflow",null],"description":"Whether a holiday calendar stood behind `must_act_by` when it was frozen onto this alert. `not_checked` means no pinned closure list verified the date: the close fell outside the office calendar’s pinned coverage years (the deterministic weekend and fixed-holiday roll may still have been applied), or the rule carries no calendar. The true close can only be the same or LATER, so a `not_checked` date is correct-or-EARLY and must not be diarised as final. Null on alerts emitted before this field existed and on alerts with no opposition window.","example":null}},"required":["severity","opposition_window_status","must_act_by","must_act_by_adjustment"]},"detected_late":{"type":"boolean","description":"True when this alert was generated well after the underlying change occurred (e.g. the monitoring pipeline recovered from a stall and processed backlogged changes). Late alerts remain fully visible here but are excluded from webhook delivery by default."},"timestamps":{"type":"object","properties":{"occurred_at":{"type":["string","null"]},"ingested_at":{"type":"string","description":"When the underlying change was ingested. Omitted when no change row is linked."},"created_at":{"type":"string"}},"required":["occurred_at","created_at"]},"links":{"type":"object","properties":{"trademark":{"type":"string"},"watch":{"type":"string"}},"required":["trademark","watch"]},"evaluation_epoch":{"type":"integer"},"provenance":{"type":"object","properties":{"sync_run":{"type":"string","description":"Ingestion run that detected this alert (prefixed sync_run ID). Omitted when the alert has no linked run (pre-provenance / unbacked rows).","example":"srun_01HK..."},"content_version":{"type":"integer","description":"The trademark_record.version the alert froze at."},"detection_latency_seconds":{"type":["integer","null"],"description":"created_at − occurred_at, in seconds. Null when the source-published time (occurred_at) is unknown or in the future relative to created_at (never negative)."},"late_detection":{"type":"boolean","description":"True when detection latency exceeded the internal per-office SLO. False whenever latency is unknown (never flags lateness that cannot be proven)."}},"required":["content_version","detection_latency_seconds","late_detection"],"description":"Evidence chain for the alert: which ingestion run detected it, the content version, and the office-published → detected latency with lateness flagged."}},"required":["id","object","schema_version","watch","customer_reference","event","match","trademark","deadline","detected_late","timestamps","links","evaluation_epoch","provenance"]}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"Alert":{"type":"object","properties":{"id":{"type":"string","example":"alt_01HK..."},"object":{"type":"string","enum":["alert"]},"schema_version":{"type":"string","enum":["2026-06-01"]},"watch":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["mark","portfolio","owner","class","similarity"]}},"required":["id","name","type"]},"customer_reference":{"type":["string","null"],"description":"Customer passthrough set on the watch; null if unset."},"event":{"type":"object","properties":{"type":{"type":"string","enum":["trademark.created","trademark.updated","trademark.status_changed","trademark.retracted","trademark.corrected"]},"summary":{"type":"string","description":"Short human-readable description, e.g. \"Status changed: pending → registered\"."},"diff":{"type":"array","items":{"$ref":"#/components/schemas/AlertDiffEntry"},"description":"Field-level change diff. Entry `path` values are the underlying flat change-tracking field tokens (e.g. `status_primary`) and intentionally differ from the nested `trademark` object keys (e.g. `status.primary`); treat them as opaque field identifiers."},"diff_truncated":{"type":"boolean","description":"Present and `true` when the change diff was bounded (entries dropped past the max count, or an over-long from/to value replaced with a sentinel, or a byte-budget cap hit). Absent when the diff is complete."}},"required":["type","summary","diff"]},"match":{"type":["object","null"],"properties":{"reason":{"type":["string","null"]},"score":{"type":["number","null"]},"score_basis":{"type":["string","null"]},"tier":{"type":["string","null"],"enum":["identical","near_identical","similar","related",null],"description":"Similarity tier of the matched mark, the same label a search hit carries as `match.tier` (identical, near_identical, similar, related). A retrieval category, not a measured edit distance. Null for filter-only watches, marks found only by their number, and alerts emitted before the field existed."}},"required":["reason","score","score_basis","tier"],"description":"Match metadata (why/how the mark matched the watch). Null for pure-filter / pre-v2 alerts that carry no match scoring. `score` is the engine score for the watch query, not the 0-100 search `relevance_score`."},"trademark":{"$ref":"#/components/schemas/AlertTrademark"},"deadline":{"type":"object","properties":{"severity":{"type":"string","enum":["normal","high","critical"]},"opposition_window_status":{"type":["string","null"],"enum":["open","closing_soon","critical","closed",null]},"must_act_by":{"type":["string","null"]},"must_act_by_adjustment":{"type":["string","null"],"enum":["moved","unchanged","not_checked","month_end_overflow",null],"description":"Whether a holiday calendar stood behind `must_act_by` when it was frozen onto this alert. `not_checked` means no pinned closure list verified the date: the close fell outside the office calendar’s pinned coverage years (the deterministic weekend and fixed-holiday roll may still have been applied), or the rule carries no calendar. The true close can only be the same or LATER, so a `not_checked` date is correct-or-EARLY and must not be diarised as final. Null on alerts emitted before this field existed and on alerts with no opposition window.","example":null}},"required":["severity","opposition_window_status","must_act_by","must_act_by_adjustment"]},"detected_late":{"type":"boolean","description":"True when this alert was generated well after the underlying change occurred (e.g. the monitoring pipeline recovered from a stall and processed backlogged changes). Late alerts remain fully visible here but are excluded from webhook delivery by default."},"timestamps":{"type":"object","properties":{"occurred_at":{"type":["string","null"]},"ingested_at":{"type":"string","description":"When the underlying change was ingested. Omitted when no change row is linked."},"created_at":{"type":"string"}},"required":["occurred_at","created_at"]},"links":{"type":"object","properties":{"trademark":{"type":"string"},"watch":{"type":"string"}},"required":["trademark","watch"]},"evaluation_epoch":{"type":"integer"},"provenance":{"type":"object","properties":{"sync_run":{"type":"string","description":"Ingestion run that detected this alert (prefixed sync_run ID). Omitted when the alert has no linked run (pre-provenance / unbacked rows).","example":"srun_01HK..."},"content_version":{"type":"integer","description":"The trademark_record.version the alert froze at."},"detection_latency_seconds":{"type":["integer","null"],"description":"created_at − occurred_at, in seconds. Null when the source-published time (occurred_at) is unknown or in the future relative to created_at (never negative)."},"late_detection":{"type":"boolean","description":"True when detection latency exceeded the internal per-office SLO. False whenever latency is unknown (never flags lateness that cannot be proven)."}},"required":["content_version","detection_latency_seconds","late_detection"],"description":"Evidence chain for the alert: which ingestion run detected it, the content version, and the office-published → detected latency with lateness flagged."},"request_id":{"type":"string"}},"required":["id","object","schema_version","watch","customer_reference","event","match","trademark","deadline","detected_late","timestamps","links","evaluation_epoch","provenance","request_id"]},"WatchDeprecation":{"type":"object","properties":{"param":{"type":"string","example":"query.strategies"},"replacement":{"type":"string","example":"query.similarity"},"sunset":{"type":"string","description":"Date the deprecated key stops being accepted (YYYY-MM-DD).","example":"2026-12-28"}},"required":["param","replacement","sunset"]},"Watch":{"type":"object","properties":{"id":{"type":"string","example":"wat_01HK..."},"object":{"type":"string","enum":["watch"]},"name":{"type":"string"},"watch_type":{"type":"string","enum":["mark","portfolio","owner","class","similarity"]},"query":{"type":"object","additionalProperties":{}},"delivery_mode":{"type":"string","enum":["always_per_alert","digest_above_threshold","digest_only"]},"status":{"type":"string","enum":["active","paused","disabled","paused_insufficient_credits"]},"alert_count_24h":{"type":["integer","null"],"description":"Number of alerts the watch has generated in the last 24 hours. **Only populated on GET /v1/watches/{id}**; always `null` on list responses (`GET /v1/watches`) to avoid an N+1 query per row. Call the GET-by-id endpoint to retrieve the count for a specific watch."},"health_status":{"type":["string","null"],"enum":["healthy","pending","lagging","degraded","unsupported","paused",null],"description":"Honest health state of the watch: healthy | pending | lagging | degraded | unsupported | paused. Populated on `GET /v1/watches` (list) and `GET /v1/watches/{id}`; `null` on create/update responses. `unsupported` means the watch scope includes an office Signa does not ingest — it never reads as healthy-with-zero-alerts. Precedence: paused > unsupported > degraded > lagging > pending > healthy."},"health":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["healthy","pending","lagging","degraded","unsupported","paused"]},"evaluated_at":{"type":["string","null"],"description":"Max last_evaluated_at (evaluation wall-clock) across in-scope offices."},"evaluations_30d":{"type":["integer","null"]},"issues":{"type":"array","items":{"type":"string","enum":["office_lagging","evaluation_backlog","failing","unresolved_target","never_evaluated","unsupported_office","config_changed_pending","invalid_filter"]},"description":"Distinct issues across the watch: every per-office `issue`, plus `invalid_filter` when the stored `niceClasses` include a value outside 1-45 (saved before that check existed). Remove the value with PATCH /v1/watches/{id}."},"offices":{"type":"array","items":{"type":"object","properties":{"office_code":{"type":"string","description":"WIPO ST.3 office code (uppercase, e.g. `US`, `EM`).","example":"US"},"status":{"type":"string","description":"ok when the office is healthy, otherwise the issue slug."},"coverage_through":{"type":["string","null"],"description":"Office-DATA timestamp through which this watch has been evaluated for this office (frozen at evaluation time — NOT wall-clock). Stops advancing when the office lags; null before the first evaluation or for unsupported offices."},"coverage_basis":{"type":["string","null"],"enum":["source_dates","date_range","run_completed",null],"description":"Which derivation rung produced coverage_through: source_dates (strongest) > date_range > run_completed (weakest)."},"last_evaluated_at":{"type":["string","null"],"description":"Evaluation wall-clock (when the evaluator last ran) — NOT a coverage claim."},"evaluations_30d":{"type":["integer","null"],"description":"Count of evaluations (receipts) for this office over the trailing 30 days. Null on list rows."},"issue":{"type":["string","null"],"enum":["office_lagging","evaluation_backlog","failing","unresolved_target","never_evaluated","unsupported_office","config_changed_pending",null]},"last_error":{"type":["string","null"],"description":"Sanitized classification of the last evaluation error (never a raw error string): entity_unresolved, entity_group_too_large, opensearch_query_rejected, budget_declined (the last sync run for this office was declined over the live-candidate budget and was NOT evaluated for this watch — an operator re-drive is required), or internal_evaluation_error."}},"required":["office_code","status","coverage_through","coverage_basis","last_evaluated_at","evaluations_30d","issue","last_error"]}}},"required":["status","evaluated_at","evaluations_30d","issues","offices"],"description":"Full health object with per-office coverage and issues. **Only populated on GET /v1/watches/{id}**; `null` on list responses (batched to two extra queries per page). Health certifies that evaluation occurred through the stated office-data horizon; it does not certify that every relevant mark was surfaced (bounded by search strategy + connector coverage)."},"last_alerted_at":{"type":["string","null"]},"customer_reference":{"type":["string","null"],"description":"Customer-supplied passthrough string echoed verbatim onto every alert this watch produces (`data.customer_reference`). `null` when unset. Set/clear it via POST/PATCH /v1/watches.","example":"PO-4242"},"metadata":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deprecations":{"type":"array","items":{"$ref":"#/components/schemas/WatchDeprecation"},"description":"Present on create, update and bulk responses when the written query used a deprecated key: `strategies` (replaced by `similarity`) or `min_match_tier` (replaced by `min_tier`). The watch is kept as a legacy watch with its original matching until it is re-saved without them. Each entry names the key, its replacement and the date the old key stops being accepted."},"request_id":{"type":"string"}},"required":["id","object","name","watch_type","query","delivery_mode","status","alert_count_24h","health_status","health","last_alerted_at","customer_reference","metadata","created_at","updated_at","request_id"]},"WatchList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"wat_01HK..."},"object":{"type":"string","enum":["watch"]},"name":{"type":"string"},"watch_type":{"type":"string","enum":["mark","portfolio","owner","class","similarity"]},"query":{"type":"object","additionalProperties":{}},"delivery_mode":{"type":"string","enum":["always_per_alert","digest_above_threshold","digest_only"]},"status":{"type":"string","enum":["active","paused","disabled","paused_insufficient_credits"]},"alert_count_24h":{"type":["integer","null"],"description":"Number of alerts the watch has generated in the last 24 hours. **Only populated on GET /v1/watches/{id}**; always `null` on list responses (`GET /v1/watches`) to avoid an N+1 query per row. Call the GET-by-id endpoint to retrieve the count for a specific watch."},"health_status":{"type":["string","null"],"enum":["healthy","pending","lagging","degraded","unsupported","paused",null],"description":"Honest health state of the watch: healthy | pending | lagging | degraded | unsupported | paused. Populated on `GET /v1/watches` (list) and `GET /v1/watches/{id}`; `null` on create/update responses. `unsupported` means the watch scope includes an office Signa does not ingest — it never reads as healthy-with-zero-alerts. Precedence: paused > unsupported > degraded > lagging > pending > healthy."},"health":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["healthy","pending","lagging","degraded","unsupported","paused"]},"evaluated_at":{"type":["string","null"],"description":"Max last_evaluated_at (evaluation wall-clock) across in-scope offices."},"evaluations_30d":{"type":["integer","null"]},"issues":{"type":"array","items":{"type":"string","enum":["office_lagging","evaluation_backlog","failing","unresolved_target","never_evaluated","unsupported_office","config_changed_pending","invalid_filter"]},"description":"Distinct issues across the watch: every per-office `issue`, plus `invalid_filter` when the stored `niceClasses` include a value outside 1-45 (saved before that check existed). Remove the value with PATCH /v1/watches/{id}."},"offices":{"type":"array","items":{"type":"object","properties":{"office_code":{"type":"string","description":"WIPO ST.3 office code (uppercase, e.g. `US`, `EM`).","example":"US"},"status":{"type":"string","description":"ok when the office is healthy, otherwise the issue slug."},"coverage_through":{"type":["string","null"],"description":"Office-DATA timestamp through which this watch has been evaluated for this office (frozen at evaluation time — NOT wall-clock). Stops advancing when the office lags; null before the first evaluation or for unsupported offices."},"coverage_basis":{"type":["string","null"],"enum":["source_dates","date_range","run_completed",null],"description":"Which derivation rung produced coverage_through: source_dates (strongest) > date_range > run_completed (weakest)."},"last_evaluated_at":{"type":["string","null"],"description":"Evaluation wall-clock (when the evaluator last ran) — NOT a coverage claim."},"evaluations_30d":{"type":["integer","null"],"description":"Count of evaluations (receipts) for this office over the trailing 30 days. Null on list rows."},"issue":{"type":["string","null"],"enum":["office_lagging","evaluation_backlog","failing","unresolved_target","never_evaluated","unsupported_office","config_changed_pending",null]},"last_error":{"type":["string","null"],"description":"Sanitized classification of the last evaluation error (never a raw error string): entity_unresolved, entity_group_too_large, opensearch_query_rejected, budget_declined (the last sync run for this office was declined over the live-candidate budget and was NOT evaluated for this watch — an operator re-drive is required), or internal_evaluation_error."}},"required":["office_code","status","coverage_through","coverage_basis","last_evaluated_at","evaluations_30d","issue","last_error"]}}},"required":["status","evaluated_at","evaluations_30d","issues","offices"],"description":"Full health object with per-office coverage and issues. **Only populated on GET /v1/watches/{id}**; `null` on list responses (batched to two extra queries per page). Health certifies that evaluation occurred through the stated office-data horizon; it does not certify that every relevant mark was surfaced (bounded by search strategy + connector coverage)."},"last_alerted_at":{"type":["string","null"]},"customer_reference":{"type":["string","null"],"description":"Customer-supplied passthrough string echoed verbatim onto every alert this watch produces (`data.customer_reference`). `null` when unset. Set/clear it via POST/PATCH /v1/watches.","example":"PO-4242"},"metadata":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deprecations":{"type":"array","items":{"$ref":"#/components/schemas/WatchDeprecation"},"description":"Present on create, update and bulk responses when the written query used a deprecated key: `strategies` (replaced by `similarity`) or `min_match_tier` (replaced by `min_tier`). The watch is kept as a legacy watch with its original matching until it is re-saved without them. Each entry names the key, its replacement and the date the old key stops being accepted."}},"required":["id","object","name","watch_type","query","delivery_mode","status","alert_count_24h","health_status","health","last_alerted_at","customer_reference","metadata","created_at","updated_at"]}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"WatchDiagnostics":{"type":"object","properties":{"watch_id":{"type":"string","example":"wat_01HK..."},"trademark_id":{"type":"string","example":"tm_01HK..."},"office_code":{"type":["string","null"]},"evaluated":{"type":"boolean"},"office_in_scope":{"type":"boolean"},"candidacy_passed":{"type":"boolean"},"trigger_event_type":{"type":["string","null"]},"trigger_event_in_filter":{"type":"boolean"},"opensearch_score":{"type":["number","null"]},"score_threshold":{"type":["number","null"]},"min_match_tier":{"type":["string","null"],"enum":["exact","normalized","fuzzy","phonetic",null]},"similarity_applied":{"type":["array","null"],"items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"The similarity channels the watch query runs. Null without q, and for a legacy watch (stored with the deprecated keys, or before v3 and not re-saved since)."},"min_tier":{"type":["string","null"],"enum":["identical","near_identical","similar","related",null],"description":"The weakest similarity tier that alerts. Null for a legacy watch (stored with the deprecated keys, or before v3 and not re-saved since), which reports min_match_tier."},"alert_fired":{"type":"boolean"},"reason":{"type":"string"},"delivery_mode_effective":{"type":["string","null"],"enum":["per_alert","digest",null]},"lease_state":{"type":["string","null"],"enum":["held","released","abandoned","epoch_raced","cas_lost",null]},"evaluation_epoch":{"type":"integer"},"replay_epoch_origin":{"type":["integer","null"]},"last_relevant_sync_run":{"type":["object","null"],"properties":{"id":{"type":"string","description":"Raw sync_runs UUID. sync_runs is a global operational table (ingestion runs, not org-scoped), so this is an operational run identifier, not a cross-tenant reference."},"sync_run":{"type":"string","description":"Prefixed form (srun_) of the same sync_runs id, matching alert.provenance.sync_run. Prefer this over the raw `id`.","example":"srun_01HK..."},"office_code":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"search_indexed_at":{"type":["string","null"]}},"required":["id","sync_run","office_code","completed_at","search_indexed_at"]},"alert_id":{"type":["string","null"],"description":"Public ID (alt_...) of the alert that fired, or null. Cross-reference against alert_id on GET /v1/webhooks/{id}/deliveries rows."},"opposition":{"type":["object","null"],"properties":{"must_act_by":{"type":["string","null"]},"rule_id":{"type":["string","null"]},"rule_source":{"type":["string","null"]},"rule_version":{"type":["string","null"]},"recomputed_close":{"type":["string","null"]},"close_adjustment":{"type":["string","null"],"enum":["moved","unchanged","not_checked","month_end_overflow",null]},"window_status":{"type":["string","null"],"enum":["open","closed","not_started","unknown",null]}},"required":["must_act_by","rule_id","rule_source","rule_version","recomputed_close","close_adjustment","window_status"]},"evaluation_consecutive_failures":{"type":["integer","null"],"description":"Consecutive evaluation failures recorded on this watch/office checkpoint (0 = healthy; null = no checkpoint row). A persistent 1 with an entity_* error means the entity target no longer resolves."},"last_evaluation_error":{"type":["string","null"],"description":"Sanitized classification of the last evaluation error for this office (never a raw error string): entity_unresolved, entity_group_too_large, opensearch_query_rejected, budget_declined (the last sync run was declined over the live-candidate budget and was NOT evaluated for this watch — operator re-drive required), or internal_evaluation_error."},"data_window":{"type":"object","properties":{"trademark_changes_retention_days":{"type":"integer"},"outbox_retention_days":{"type":"integer"},"indexing_status_retention_days":{"type":"integer"},"deliveries_retention_days":{"type":"integer"},"alerts_retention_days":{"type":"integer"},"diagnostic_freshness_horizon_days":{"type":"integer"}},"required":["trademark_changes_retention_days","outbox_retention_days","indexing_status_retention_days","deliveries_retention_days","alerts_retention_days","diagnostic_freshness_horizon_days"]},"request_id":{"type":"string"}},"required":["watch_id","trademark_id","office_code","evaluated","office_in_scope","candidacy_passed","trigger_event_type","trigger_event_in_filter","opensearch_score","score_threshold","min_match_tier","similarity_applied","min_tier","alert_fired","reason","delivery_mode_effective","lease_state","evaluation_epoch","replay_epoch_origin","last_relevant_sync_run","alert_id","opposition","evaluation_consecutive_failures","last_evaluation_error","data_window","request_id"]},"WatchAttestationGap":{"type":"object","properties":{"from":{"type":"string"},"through":{"type":"string"},"reason":{"type":"string","enum":["office_lagging","evaluation_missing","evaluation_failed","budget_declined"],"description":"office_lagging = evaluations ran but the office data they covered was stale beyond the office SLO; evaluation_missing = NO evaluation ran for this interval although it should have (an eligible sync run has no evaluation receipt for this watch — pause, credit lock, lease starvation — or no evaluation evidence exists for longer than the continuity backstop); budget_declined = a sync run for this office exceeded the evaluator per-run change budget and was NOT evaluated (no receipt, no checkpoint advance) — the window is only resolved by an audited re-drive or a recorded suppression, never by later coverage, and such a run is never ALSO reported as evaluation_missing; evaluation_failed = reserved."},"resolved":{"type":"boolean","description":"For office_lagging: coverage caught back up within the period. For evaluation_missing: evaluation demonstrably resumed at the end of the interval. For budget_declined: an operator closed it within the period (see `resolution`); a resolution AFTER the period is deliberately invisible here, so a closed period never mutates."},"sync_run_id":{"type":"string","description":"Present only on budget_declined gaps: the sync run that was declined without evaluation."},"resolution":{"type":"string","enum":["redriven","suppressed"],"description":"Present only on a RESOLVED budget_declined gap. redriven = the run was re-evaluated with a raised budget (the changes were eventually assessed). suppressed = an operator recorded the deliberate decision that this run will never be evaluated. These are not the same claim, so they are never collapsed into a bare resolved: true."}},"required":["from","through","reason","resolved"]},"WatchAttestationOffice":{"type":"object","properties":{"office_code":{"type":"string"},"office_name":{"type":"string"},"status":{"type":"string","enum":["evaluated","no_evaluations","unsupported"],"description":"evaluated = a supported (ingested) office with real evaluation claims; no_evaluations = a supported office with ZERO evaluations in the period (zero counts, no coverage claims, and a full-period gap — an un-evaluated month never reads as a clean silent month); unsupported = an in-scope office Signa does not ingest — NO evaluation claims are made for it."},"evaluations_count":{"type":"integer"},"sync_runs_evaluated":{"type":"array","items":{"type":"string"}},"changes_evaluated":{"type":"integer","description":"Changes evaluated against your query this period (candidacy volume, sum of per-run candidate changes). NOT the size of the whole office corpus."},"match_count":{"type":"integer"},"alerts_emitted":{"type":"integer"},"coverage_from":{"type":["string","null"]},"coverage_through":{"type":["string","null"]},"coverage_basis":{"type":["string","null"],"enum":["source_dates","date_range","run_completed",null]},"gaps":{"type":"array","items":{"$ref":"#/components/schemas/WatchAttestationGap"}},"evaluation_resumed_after_period":{"type":"boolean","description":"Present on every supported office (no_evaluations and evaluated alike): evaluation demonstrably resumed for this office AFTER the period. A generation-time fact, so it is EXCLUDED from content_hash (like watch_status_at_generation) — the period gaps themselves stay permanently unresolved, because nothing that happens later can evaluate that month."}},"required":["office_code","office_name","status"]},"WatchAttestation":{"type":"object","properties":{"object":{"type":"string","enum":["watch_attestation"]},"schema_version":{"type":"string"},"watch":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Display-only; excluded from content_hash (mutable via PATCH)."},"query_fingerprint":{"type":"string"},"fingerprint_basis":{"type":"string","enum":["current_configuration"],"description":"The fingerprint describes the CURRENT watch configuration (a true evaluated-time snapshot requires the deferred watch-revision history). Cross-check the two configuration_changed_* flags."},"trigger_events":{"type":"array","items":{"type":"string"}},"configuration_changed_in_period":{"type":"boolean","description":"True when evaluation-epoch deltas occurred WITHIN the period (from receipts)."},"configuration_changed_since_period":{"type":"boolean","description":"True when the live watch configuration epoch is ahead of every epoch seen in the period — a post-period change happened, so the (current-configuration) fingerprint no longer describes the period. Generation-time fact; excluded from content_hash."},"epochs_in_period":{"type":"array","items":{"type":"integer"}}},"required":["id","name","query_fingerprint","fingerprint_basis","trigger_events","configuration_changed_in_period","configuration_changed_since_period"]},"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"},"partial":{"type":"boolean"}},"required":["start","end","partial"]},"offices":{"type":"array","items":{"$ref":"#/components/schemas/WatchAttestationOffice"}},"totals":{"type":"object","properties":{"evaluations":{"type":"integer"},"alerts_emitted":{"type":"integer"},"declined_runs":{"type":"integer","description":"Office sync runs in the period that were DECLINED without evaluation (evaluator per-run change budget). Each is disclosed as a budget_declined gap on its office."},"declined_runs_unresolved":{"type":"integer","description":"Subset of declined_runs still outstanding at the end of the period (no re-drive and no recorded suppression)."}},"required":["evaluations","alerts_emitted","declined_runs","declined_runs_unresolved"]},"reconciliation":{"type":"string","enum":["consistent","mismatch"],"description":"Cross-check of receipts.alerts_inserted vs stored alert rows for the period, scoped to the supported-office set. Alerts that cannot be office-attributed (null sync_run reference, e.g. pruned) are counted — a residual mismatch source disclosed rather than dropped."},"statement":{"type":"string"},"slo_reference":{"type":"string"},"watch_status_at_generation":{"type":"string","description":"Present ('paused' | 'disabled') when the watch is not active at generation time. Pause history within the period is not reconstructable in v1. Generation-time fact; excluded from content_hash."},"generated_at":{"type":"string"},"content_hash":{"type":"string","description":"sha256 over the canonical (sorted-key) artifact excluding generated_at, request_id, content_hash, watch_status_at_generation, watch.name, watch.configuration_changed_since_period, and offices[].evaluation_resumed_after_period. Re-fetch the same closed period and compare to verify INTEGRITY of the artifact. This is not a third-party authenticity signature; signed/timestamped documents are roadmap."},"request_id":{"type":"string"}},"required":["object","schema_version","watch","period","offices","totals","reconciliation","statement","slo_reference","generated_at","content_hash","request_id"]},"OfficePipelineStatus":{"type":"object","properties":{"office_code":{"type":"string","description":"WIPO ST.3 office code (uppercase, e.g. `US`, `EM`).","example":"US"},"pipeline_status":{"type":"string","enum":["ok","lagging"],"description":"ok when the office coverage is within its internal SLO; lagging when coverage is stale beyond the SLO or there is no coverage signal at all."},"coverage_through":{"type":["string","null"],"description":"Office-DATA time through which the latest eligible+indexed sync_run covers this office (shared derivation), not wall-clock time. A date-only watermark covers through the end of that UTC day but is never reported later than the time of the response. null when no eligible run carries a coverage signal."},"last_completed_sync_at":{"type":["string","null"],"description":"Newest completed sync-run instant (office pull finished), regardless of indexing."},"last_search_indexed_at":{"type":["string","null"],"description":"When the latest eligible run for this office became searchable (search_indexed_at)."},"slo_hours":{"type":"integer","description":"Internal freshness ceiling (hours) derived from the office cadence. Drives pipeline_status; NOT a published SLA."},"declined_runs_unresolved":{"type":"integer","description":"Sync runs for this office in the last 30 days that the evaluator DECLINED without evaluating (the run exceeded the per-run change budget) and that have no audited re-drive recorded. Non-zero means changes from those runs have not been evaluated against any watch; the affected periods are disclosed as budget_declined gaps in watch attestations."}},"required":["office_code","pipeline_status","coverage_through","last_completed_sync_at","last_search_indexed_at","slo_hours","declined_runs_unresolved"]},"MonitoringStatus":{"type":"object","properties":{"object":{"type":"string","enum":["monitoring_status"]},"watches":{"type":"object","properties":{"total":{"type":"integer"},"by_health":{"type":"object","properties":{"healthy":{"type":"integer"},"lagging":{"type":"integer"},"degraded":{"type":"integer"},"paused":{"type":"integer"},"pending":{"type":"integer"},"unsupported":{"type":"integer"}},"required":["healthy","lagging","degraded","paused","pending","unsupported"],"description":"Count of the org watches in each honest health state."}},"required":["total","by_health"],"description":"Org-scoped watch-health aggregate over ALL of the org watches."},"offices":{"type":"array","items":{"$ref":"#/components/schemas/OfficePipelineStatus"},"description":"GLOBAL per-live-office pipeline status (not org-specific). Computed once and shared across orgs via a 60s cache."},"pipeline":{"type":"object","properties":{"last_verified_end_to_end_at":{"type":["string","null"],"description":"The synthetic end-to-end heartbeat: when the pipeline was last verified through the real production bus. NULL-HONEST: null when never recorded OR when the most recent heartbeat is stale beyond the freshness horizon — a stale value is never presented as a fresh verification. Distinct from last_real_record_alert_at."},"last_real_record_alert_at":{"type":["string","null"],"description":"When the representative real-record canary path last saw an office-originated change. A SEPARATE, slower signal from the synthetic heartbeat (which only proves the bus is alive now). Same null-honesty as above."},"verification":{"type":"string","enum":["canary"],"description":"The verification mechanism behind these timestamps."}},"required":["last_verified_end_to_end_at","last_real_record_alert_at","verification"],"description":"Continuous pipeline-verification signals (facet B canary)."},"request_id":{"type":"string"}},"required":["object","watches","offices","pipeline","request_id"]},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","example":"whk_01HK..."},"object":{"type":"string","enum":["webhook_endpoint"]},"url":{"type":"string"},"description":{"type":["string","null"]},"enabled_events":{"type":"array","items":{"type":"string"}},"portfolio_id":{"type":["string","null"],"description":"Optional portfolio scope. Applies to every event type, alert.created included: the endpoint receives an event only when its mark was a member of this portfolio at event time."},"status":{"type":"string","enum":["active","disabled"]},"secret_version":{"type":"integer"},"consecutive_failures":{"type":"integer"},"last_success_at":{"type":["string","null"]},"last_failure_at":{"type":["string","null"]},"disabled_at":{"type":["string","null"],"description":"When the endpoint last transitioned to status=disabled (manual or automatic). Null when never disabled or for pre-FX3.B history."},"disabled_reason":{"type":["string","null"],"description":"Slug explaining the disable. One of 'auto_consecutive_100' (100 consecutive failures), 'auto_failure_rate_50_over_50' (>50% failure rate over a rolling 50-attempt window), 'manual' (PATCH or DELETE), or null."},"metadata":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"secret":{"type":"string"},"request_id":{"type":"string"}},"required":["id","object","url","description","enabled_events","portfolio_id","status","secret_version","consecutive_failures","last_success_at","last_failure_at","disabled_at","disabled_reason","metadata","created_at","updated_at","request_id"]},"WebhookList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"whk_01HK..."},"object":{"type":"string","enum":["webhook_endpoint"]},"url":{"type":"string"},"description":{"type":["string","null"]},"enabled_events":{"type":"array","items":{"type":"string"}},"portfolio_id":{"type":["string","null"],"description":"Optional portfolio scope. Applies to every event type, alert.created included: the endpoint receives an event only when its mark was a member of this portfolio at event time."},"status":{"type":"string","enum":["active","disabled"]},"secret_version":{"type":"integer"},"consecutive_failures":{"type":"integer"},"last_success_at":{"type":["string","null"]},"last_failure_at":{"type":["string","null"]},"disabled_at":{"type":["string","null"],"description":"When the endpoint last transitioned to status=disabled (manual or automatic). Null when never disabled or for pre-FX3.B history."},"disabled_reason":{"type":["string","null"],"description":"Slug explaining the disable. One of 'auto_consecutive_100' (100 consecutive failures), 'auto_failure_rate_50_over_50' (>50% failure rate over a rolling 50-attempt window), 'manual' (PATCH or DELETE), or null."},"metadata":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","url","description","enabled_events","portfolio_id","status","secret_version","consecutive_failures","last_success_at","last_failure_at","disabled_at","disabled_reason","metadata","created_at","updated_at"]}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"WebhookDeliveryList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_delivery"]},"endpoint_id":{"type":"string"},"alert_id":{"type":["string","null"]},"event_id":{"type":"string"},"event_type":{"type":"string"},"attempt":{"type":"integer"},"delivery_attempt_id":{"type":"string"},"status":{"type":"string"},"http_status":{"type":["integer","null"]},"response_body":{"type":["string","null"]},"error_reason":{"type":["string","null"]},"signature_timestamp":{"type":"string"},"next_retry_at":{"type":["string","null"]},"delivered_at":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","object","endpoint_id","alert_id","event_id","event_type","attempt","delivery_attempt_id","status","http_status","response_body","error_reason","signature_timestamp","next_retry_at","delivered_at","created_at"]}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_delivery"]},"endpoint_id":{"type":"string"},"alert_id":{"type":["string","null"]},"event_id":{"type":"string"},"event_type":{"type":"string"},"attempt":{"type":"integer"},"delivery_attempt_id":{"type":"string"},"status":{"type":"string"},"http_status":{"type":["integer","null"]},"response_body":{"type":["string","null"]},"error_reason":{"type":["string","null"]},"signature_timestamp":{"type":"string"},"next_retry_at":{"type":["string","null"]},"delivered_at":{"type":["string","null"]},"created_at":{"type":"string"},"request_id":{"type":"string"}},"required":["id","object","endpoint_id","alert_id","event_id","event_type","attempt","delivery_attempt_id","status","http_status","response_body","error_reason","signature_timestamp","next_retry_at","delivered_at","created_at","request_id"]},"EventListItem":{"type":"object","properties":{"id":{"type":"string","description":"Event ID (evt_-prefixed, opaque)","example":"evt_3D7rZ9"},"object":{"type":"string","enum":["event"]},"type":{"type":"string","example":"trademark.status_changed"},"trademark_id":{"type":["string","null"],"example":"tm_abc123"},"office_code":{"type":["string","null"],"example":"US"},"occurred_at":{"type":"string"},"recorded_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","object","type","trademark_id","office_code","occurred_at","recorded_at","created_at"]},"EventList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EventListItem"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"EventDetail":{"type":"object","properties":{"id":{"type":"string","description":"Event ID (evt_-prefixed, opaque)","example":"evt_3D7rZ9"},"object":{"type":"string","enum":["event"]},"type":{"type":"string"},"payload_version":{"type":"integer","exclusiveMinimum":0},"trademark_id":{"type":["string","null"]},"alert_id":{"type":["string","null"]},"alert":{"type":"object","additionalProperties":{}},"version":{"type":["integer","null"]},"mark_text":{"type":["string","null"]},"status":{"type":["string","null"]},"status_stage":{"type":"string"},"status_reason":{"type":["string","null"]},"owner_name":{"type":["string","null"]},"jurisdiction_code":{"type":["string","null"],"description":"Public two-letter jurisdiction code. For Madrid designation events this is shape-normalized only and is never translated through the office vocabulary. WIPO's designation of the EU (stored `EM`) reads `EU`, as on the trademark row.","example":"BR"},"changed_fields":{"type":"array","items":{"type":"string"}},"changes":{"type":"object","additionalProperties":{"type":"object","properties":{"before":{},"after":{}}}},"trademark_event":{"allOf":[{"$ref":"#/components/schemas/TrademarkEvent"},{"description":"office_action.issued, payload_version 2: the prosecution-history row, exactly as GET /v1/trademarks/{id}/events serves it."}]},"event_date":{"type":"string","description":"office_action.issued, payload_version 1 only.","example":"2026-08-14"},"event_code":{"type":["string","null"],"description":"payload_version 1 only (v2: trademark_event.raw.code)."},"event_label":{"type":["string","null"],"description":"payload_version 1 only (v2: trademark_event.raw.label)."},"scope":{"type":["string","null"],"description":"payload_version 1 only (v2: trademark_event.event_scope)."},"status_after_event":{"type":["string","null"],"description":"payload_version 1 only."},"nice_class_number":{"type":["integer","null"],"description":"payload_version 1 only (v2: trademark_event.nice_class)."},"description":{"type":["string","null"],"description":"payload_version 1 only."},"source_identifier":{"type":["string","null"],"description":"payload_version 1 only."},"sequence_no":{"type":["integer","null"],"description":"payload_version 1 only (v2: trademark_event.sequence_number)."},"source_date":{"type":["string","null"],"description":"Office-reported date this event is from (YYYY-MM-DD), or null when the feed reports none. Distinct from occurred_at, which is when Signa produced the event. Day precision, and the meaning varies by office: USPTO transaction date, WIPO gazette date, snapshot offices the crawl date.","example":"2026-08-14"},"correction":{"type":"object","properties":{"kind":{"type":"string","enum":["status","late_office_record"],"description":"status: Signa published a wrong status and this event reverses it. late_office_record: office records reached Signa late and show the mark lapsing or a dead mark returning."}},"required":["kind"],"description":"trademark.corrected only: why this status change is a correction of a status Signa published earlier. The rest of the body is the trademark.status_changed shape."},"portfolios":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"ptf_9aB2xY"},"external_ref":{"type":["string","null"],"example":"MATTER-4471"}},"required":["id","external_ref"]},"description":"Portfolios this mark belonged to when the event was recorded, with the external_ref you set on the membership. Frozen at record time, so later membership or reference edits never rewrite an event you already received; null external_ref means unknown or unset. Empty when the mark was in no portfolio. Absent on alert.created."},"office_code":{"type":["string","null"]},"occurred_at":{"type":"string"},"recorded_at":{"type":"string"},"created_at":{"type":"string"},"request_id":{"type":"string"}},"required":["id","object","type","payload_version","office_code","occurred_at","recorded_at","created_at","request_id"]},"SubscriptionSummary":{"type":"object","properties":{"status":{"type":["string","null"],"description":"The organization's Stripe subscription status as mirrored (`active`, `trialing`, `past_due`, `unpaid`, `paused`, `canceled`, ...). Null when the organization has no subscription.","example":"past_due"},"cancel_at":{"type":["string","null"],"description":"When a scheduled cancellation takes effect (ISO 8601); null when none is scheduled."},"dunning":{"type":["object","null"],"properties":{"since":{"type":"string","description":"First failed payment attempt on the open invoice (ISO 8601)."},"next_attempt":{"type":["string","null"],"description":"Stripe's next automatic payment attempt (ISO 8601); null once Stripe stops retrying."},"invoice_url":{"type":["string","null"],"description":"Stripe-hosted page to pay the open invoice or update the payment method."}},"required":["since","next_attempt","invoice_url"],"description":"Present while a first or renewal invoice of the organization's LIVE subscription is unpaid and Stripe is collecting it (payment failed or needs customer action): the API keeps answering, but a pool that runs empty is refused `insufficient_credits` with `reason: \"payment_past_due\"`. Null otherwise, including after the subscription ended with the invoice left open, and for a declined plan-change payment (POST /v1/organization/billing/plan-change answers that as `pending_payment`; the current plan stays paid for)."},"scheduled_change":{"type":["object","null"],"properties":{"plan":{"type":"string","description":"The plan the subscription changes to (canonical name).","example":"starter"},"interval":{"type":"string","enum":["monthly","annual"],"description":"The billing interval it changes to.","example":"monthly"},"effective_at":{"type":"string","description":"When the change takes effect: the end of the current billing period (ISO 8601).","example":"2026-11-02T00:00:00.000Z"}},"required":["plan","interval","effective_at"],"description":"A downgrade or a switch to monthly billing made through POST /v1/organization/billing/plan-change that waits for the end of the current period; null when none is pending. Requesting the current plan and interval from that endpoint undoes it. Null once it takes effect, and once the subscription is cancelled or the change is released in Stripe."}},"required":["status","cancel_at","dunning"],"description":"The organization's subscription as Signa mirrors it (status, scheduled cancellation, open dunning record of the live subscription, plan change scheduled for the period end). Present only when the API key holds billing:read (or admin); absent otherwise."},"Identity":{"type":"object","properties":{"object":{"type":"string","enum":["identity"]},"org_id":{"type":"string","example":"orgn_abc"},"org_name":{"type":"string"},"plan":{"type":"string","example":"growth"},"billing_preview":{"type":"boolean","description":"Dark-launch preview flag (organizations.settings.billing_preview). When true, the dashboard reveals preview-gated billing/notification pages; beta orgs read false. Defaults false when unset."},"billing_hold":{"type":["object","null"],"properties":{"reason":{"type":"string","enum":["dispute","repeat_disputes"],"description":"`dispute`: a payment dispute is open or was lost. `repeat_disputes`: two or more disputes were lost within 12 months."},"permanent":{"type":"boolean","description":"True after two or more lost disputes within 12 months: a standing purchase block that only Signa support lifts. False while a single dispute is open or after it was lost; a won dispute lifts that hold, a lost one stays until support lifts it."},"since":{"type":"string","description":"When the hold was placed (ISO 8601)."}},"required":["reason","permanent","since"],"description":"Present while purchases are paused because of a payment dispute: credit and plan checkouts and the full billing portal answer 409 `billing_hold`; the portal's payment-method and cancel flows stay open. Null otherwise."},"beta_offer_eligible":{"type":"boolean","description":"True while the organization can claim the beta thank-you offer on a plan checkout (`offer: \"beta\"` on POST /v1/organization/billing/checkout): a beta organization (still on the beta plan, or moved to Free on 1 October) that has not claimed it, has no live subscription, and the offer has not closed."},"can_buy_credits":{"type":"boolean","description":"True when the organization can buy extra credits (POST /v1/organization/billing/credits/checkout). A billing hold (`billing_hold`) pauses purchases regardless."},"subscription":{"$ref":"#/components/schemas/SubscriptionSummary"},"billing_interval":{"type":["string","null"],"enum":["monthly","annual",null],"description":"The live subscription's billing interval, or null without one. With `plan` it names what the subscription bills, so a plan change (POST /v1/organization/billing/plan-change) can offer the other interval of the current plan and say whether it is charged now or takes effect at the period end."},"api_key":{"type":"object","properties":{"id":{"type":"string","example":"key_abc"},"prefix":{"type":"string","example":"sig_abcd1234"},"scopes":{"type":"array","items":{"type":"string"}},"rate_limit_tier":{"type":"string"}},"required":["id","prefix","scopes","rate_limit_tier"]},"request_id":{"type":"string"}},"required":["object","org_id","org_name","plan","billing_preview","billing_hold","beta_offer_eligible","api_key","request_id"]},"Organization":{"type":"object","properties":{"object":{"type":"string","enum":["organization"]},"org_id":{"type":"string","example":"orgn_abc"},"org_name":{"type":"string"},"request_id":{"type":"string"}},"required":["object","org_id","org_name","request_id"]},"Usage":{"type":"object","properties":{"object":{"type":"string","enum":["usage"]},"schema_versions":{"type":"array","items":{"type":"integer"},"description":"Sorted distinct credit schedule versions present in billable events for this billing period. Empty when there are no billable events.","example":[1,2]},"billing_period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"by_endpoint_type":{"type":"object","additionalProperties":{"type":"object","properties":{"used":{"type":"number","description":"Consumption of this endpoint type so far this billing period. Under `pooled` it is credits actually spent; under `plan` or `default` it is units drawn from the per-type allowance, which is what the quota limiter counts. See `limit_source`."},"beta_used":{"type":"number","description":"Credits this endpoint type would have cost, metered at the published price but NOT charged: actions that are free during their beta (see the credit schedule). Always present, 0 for anything charged. Under `pooled` it is excluded from `used`, which is money actually spent; under a per-type allowance (`plan` or `default`) there is no money to spend and beta traffic draws on the allowance like any other, so it is counted in `used` too."},"limit":{"type":["number","null"]},"limit_source":{"type":"string","enum":["plan","default","pooled"],"description":"Which regime set `limit`. `plan` = an allowance set for this plan and endpoint type. `default` = the plan's catch-all fallback — enforced all the same, but not a commitment, and liable to change when the type gets an allowance of its own. `pooled` = the organization spends one shared credit balance, so there is no per-type allowance and `limit` is null; see GET /v1/organization/credits."},"gated":{"type":"boolean","enum":[true],"description":"Present only when this endpoint type is not included in your plan. Once traffic bills under it, those requests are refused with 403 `plan_gated` before any credits are spent."}},"required":["used","beta_used","limit","limit_source"]}},"rate_limit":{"type":"object","properties":{"limit":{"type":"number"},"resets_at":{"type":"string"}},"required":["limit","resets_at"],"description":"DEPRECATED — reflects the search-tier RPM only (kept for backward compatibility). Use rate_limits for the per-endpoint-type matrix.","deprecated":true},"rate_limits":{"type":"object","additionalProperties":{"type":"number"},"description":"The plan's requests-per-minute bucket per endpoint type (search, read, monitoring, utility, reference, check). A transport-tier safety ceiling can additionally bind — e.g. mutating requests are capped at 1000/min regardless of the type bucket's RPM.","example":{"search":1000,"read":10000,"monitoring":100,"utility":1000,"reference":1000,"check":1000}},"request_id":{"type":"string"}},"required":["object","schema_versions","billing_period","by_endpoint_type","rate_limit","rate_limits","request_id"]},"OrgPlanQuotaEntry":{"type":"object","properties":{"endpoint_type":{"type":"string"},"monthly_limit":{"type":["number","null"]},"used":{"type":"number","description":"Consumption of this endpoint type so far this billing period. Under `pooled` it is credits actually spent; under `plan` or `default` it is units drawn from the per-type allowance, which is what the quota limiter counts. See `limit_source`."},"beta_used":{"type":"number","description":"Credits this endpoint type would have cost, metered at the published price but NOT charged: actions that are free during their beta (see the credit schedule). Always present, 0 for anything charged. Under `pooled` it is excluded from `used`, which is money actually spent; under a per-type allowance (`plan` or `default`) there is no money to spend and beta traffic draws on the allowance like any other, so it is counted in `used` too."},"remaining":{"type":["number","null"],"description":"`monthly_limit` minus `used`, and the number the quota middleware enforces: requests start being refused 429 `quota_exceeded` exactly when it reaches 0. Null when there is no allowance to have a remainder of — unlimited, or `pooled`, where the balance at GET /v1/organization/credits is the real answer."},"rate_limit_rpm":{"type":"number"},"daily_limit":{"type":["number","null"]},"daily_used":{"type":"number"},"daily_remaining":{"type":["number","null"]},"limit_source":{"type":"string","enum":["plan","default","pooled"],"description":"Which regime set the limits above. `plan` = an allowance set for this plan and endpoint type. `default` = the plan's catch-all fallback — enforced by the quota middleware all the same, but not a commitment, and liable to change when the type gets an allowance of its own. `pooled` = the organization spends one shared credit balance, so the per-type monthly and daily allowances do not apply and are null; see GET /v1/organization/credits. `rate_limit_rpm` applies under all three."},"gated":{"type":"boolean","enum":[true],"description":"Present only when this endpoint type is not included in your plan. Once traffic bills under it, those requests are refused with 403 `plan_gated` before any credits are spent."}},"required":["endpoint_type","monthly_limit","used","beta_used","remaining","rate_limit_rpm","daily_limit","daily_used","daily_remaining","limit_source"]},"OrgPlan":{"type":"object","properties":{"object":{"type":"string","enum":["plan"]},"plan":{"type":"string","example":"beta"},"billing_period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"quotas":{"type":"array","items":{"$ref":"#/components/schemas/OrgPlanQuotaEntry"}},"request_id":{"type":"string"}},"required":["object","plan","billing_period","quotas","request_id"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string","example":"key_abc123"},"object":{"type":"string","enum":["api_key"]},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"rate_limit_tier":{"type":"string"},"status":{"type":"string","enum":["active","revoked","expired"],"description":"Derived lifecycle state: \"revoked\" if revoked_at is set; else \"expired\" if expires_at has passed; else \"active\"."},"expires_at":{"type":["string","null"]},"rotated_at":{"type":["string","null"],"description":"When this key was rotated (superseded). Non-null means expires_at is a rotation grace deadline, not a customer-set expiry."},"last_used_at":{"type":["string","null"]},"revoked_at":{"type":["string","null"],"description":"When this key was revoked; null while it is not. A revoked key has `status: \"revoked\"`."},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_by":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"request_id":{"type":"string"}},"required":["id","object","name","prefix","scopes","rate_limit_tier","status","expires_at","rotated_at","last_used_at","revoked_at","metadata","created_by","created_at","updated_at","request_id"]},"ApiKeyWithKey":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"key":{"type":"string","example":"sig_abcdef1234567890abcdef1234567890abcdef1234567890ab"}},"required":["key"]}]},"ApiKeyList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"key_abc123"},"object":{"type":"string","enum":["api_key"]},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"rate_limit_tier":{"type":"string"},"status":{"type":"string","enum":["active","revoked","expired"],"description":"Derived lifecycle state: \"revoked\" if revoked_at is set; else \"expired\" if expires_at has passed; else \"active\"."},"expires_at":{"type":["string","null"]},"rotated_at":{"type":["string","null"],"description":"When this key was rotated (superseded). Non-null means expires_at is a rotation grace deadline, not a customer-set expiry."},"last_used_at":{"type":["string","null"]},"revoked_at":{"type":["string","null"],"description":"When this key was revoked; null while it is not. A revoked key has `status: \"revoked\"`."},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_by":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","prefix","scopes","rate_limit_tier","status","expires_at","rotated_at","last_used_at","revoked_at","metadata","created_by","created_at","updated_at"]}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"RequestLog":{"type":"object","properties":{"id":{"type":"string","description":"The logged request ID (e.g. req_01kpj...)."},"object":{"type":"string","enum":["request_log"]},"method":{"type":"string"},"path":{"type":"string"},"status_code":{"type":"integer"},"duration_ms":{"type":"integer"},"endpoint_type":{"type":"string"},"credits":{"type":"integer","description":"Credits charged against your plan for this request."},"schema_version":{"type":"integer","description":"Which published credit schedule priced `credits` on this row. 1 = the pre-launch placeholder weights; 2 = the credit schedule at signa.so/pricing. Stamped when the request ran, so a row is never repriced by a later change.","example":2},"api_key_prefix":{"type":["string","null"]},"error_type":{"type":["string","null"]},"error_detail":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","object","method","path","status_code","duration_ms","endpoint_type","credits","schema_version","api_key_prefix","error_type","error_detail","created_at"]},"RequestLogList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/RequestLog"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"RequestLogDetail":{"allOf":[{"$ref":"#/components/schemas/RequestLog"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"FeedbackResource":{"type":"object","properties":{"id":{"type":"string","example":"fbk_550e8400-e29b-41d4-a716-446655440000"},"object":{"type":"string","enum":["feedback"]},"api_key_id":{"type":["string","null"],"example":"key_1a2b3c4d-…"},"type":{"type":"string","enum":["data_issue","bug","feature_request","other"]},"status":{"type":"string","enum":["open","acknowledged","resolved"]},"message":{"type":"string"},"resource_id":{"type":["string","null"]},"request_ref":{"type":["string","null"]},"field":{"type":["string","null"]},"expected_value":{"type":["string","null"]},"context":{"type":"object","additionalProperties":{},"description":"Server-built investigation snapshots captured at submit time (never client-supplied). `context.request` is present when `request_id` was provided: an object ({ route, method, status_code, error_type, error_detail, duration_ms, occurred_at }) when the request is found within your organization, or `null` for an unknown or foreign request id. `context.resource` is present when `resource_id` referenced a snapshot-supported entity (trademark, owner, attorney, firm, proceeding): { found: true, resource_type, office, jurisdiction, version, status_primary, source_updated_at, updated_at } with nulls where a type lacks a field (`office` is the WIPO ST.3 office code, e.g. `US`, `EM`), or { found: false, resource_type } when the record does not exist. A key is absent when the reference was not provided or the snapshot could not be captured — enrichment never rejects a submission.","example":{"request":{"route":"/v1/trademarks/{id}","method":"GET","status_code":404,"error_type":"not_found","error_detail":"Trademark tm_… does not exist.","duration_ms":12,"occurred_at":"2026-07-10T12:34:56.000Z"},"resource":{"found":true,"resource_type":"trademark","office":"US","jurisdiction":"US","version":3,"status_primary":"active","source_updated_at":"2026-07-01T00:00:00.000Z","updated_at":"2026-07-02T08:00:00.000Z"}}},"resolution_note":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"resolved_at":{"type":["string","null"]}},"required":["id","object","api_key_id","type","status","message","resource_id","request_ref","field","expected_value","context","resolution_note","metadata","created_at","updated_at","resolved_at"]},"Feedback":{"allOf":[{"$ref":"#/components/schemas/FeedbackResource"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"FeedbackList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackResource"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","request_id"]},"UsageSummaryItem":{"type":"object","properties":{"period_start":{"type":"string"},"endpoint_type":{"type":"string"},"api_key_id":{"type":["string","null"]},"request_count":{"type":"integer"},"credits":{"type":"integer","description":"Credits metered for billable requests in this bucket. Actions that are free during the beta (screening, listing screening, compare) are metered here at their full nominal weight but are not charged; billing_period.credits_used is the charged figure."},"error_count":{"type":"integer"},"avg_duration_ms":{"type":["integer","null"]}},"required":["period_start","endpoint_type","request_count","credits","error_count","avg_duration_ms"]},"BillingPeriodContext":{"type":"object","properties":{"start":{"type":"string","description":"Start of the period this block describes: the current plan pool's own window (the active plan grant's effective_at) for organizations on a credit plan; the anchor-day billing period otherwise."},"end":{"type":"string","description":"End of the period this block describes: when the current plan pool expires (the active plan grant's expires_at) for organizations on a credit plan; the anchor-day billing period end otherwise."},"credits_used":{"type":"integer","description":"Credits consumed from the current plan pool: the active plan grants of this period (net of credits a refund or dispute revoked); 0 while no plan grant is active. Purchased, signup and promo credits are not part of this figure, and an endpoint_type filter does not narrow it. Legacy (beta) organizations report the credits charged in the billing period instead, excluding actions that are free during the beta."},"credits_limit":{"type":["integer","null"],"description":"Pooled monthly credit allowance; null for unlimited plans."},"credits_remaining":{"type":["integer","null"],"description":"Credits remaining in the current billing period, after charged usage only; null for unlimited plans."},"defaulted":{"type":"boolean","description":"True when the response date range fell back to the current billing period because both start_date and end_date were omitted."}},"required":["start","end","credits_used","credits_limit","credits_remaining","defaulted"]},"UsageSummaryResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageSummaryItem"}},"has_more":{"type":"boolean"},"pagination":{"type":"object","properties":{"cursor":{"type":["string","null"]},"total_count":{"type":"integer"},"total_count_approximate":{"type":"boolean"}},"required":["cursor"]},"billing_period":{"$ref":"#/components/schemas/BillingPeriodContext"},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","billing_period","request_id"]},"UsageEstimateAction":{"type":"object","properties":{"action_id":{"type":"string","description":"Schedule action id, or a synthetic bucket: `unmapped` (route nothing recognises), `unrouted` (authenticated 404), `removed:<path>`, `unpriced:<path>`, `free:<type>`.","example":"search"},"name":{"type":"string","example":"Search"},"requests":{"type":"integer"},"quantity":{"type":"number","description":"Charged quantity in the action's own unit (pages, records, items, requests)."},"credits":{"type":"integer","description":"Credits the org would have been charged."},"nominal_credits":{"type":"integer","description":"The same traffic at list price, including what the launch beta waives."},"disposition":{"type":"string","enum":["charged","beta_free","free","mixed","unpriced"],"description":"charged = debited; beta_free = metered at full price, never debited; free = a zero-price action or non-billable requests; mixed = both, for a window straddling a GA switch; unpriced = no price exists for the route."}},"required":["action_id","name","requests","quantity","credits","nominal_credits","disposition"]},"UsageEstimateUnmapped":{"type":"object","properties":{"route":{"type":"string","example":"/v1/brand-new-thing"},"method":{"type":"string","example":"GET"},"endpoint_type":{"type":"string","example":"read"},"requests":{"type":"integer"},"credits":{"type":"integer","description":"Credits these requests really cost. Non-zero only after the cutover."}},"required":["route","method","endpoint_type","requests","credits"]},"UsageEstimatePlan":{"type":"object","properties":{"id":{"type":"string","example":"growth"},"name":{"type":"string","example":"Growth"},"credits_included":{"type":["integer","null"]},"per_month_annual":{"type":["number","null"],"description":"Price per month when billed yearly, USD."},"monthly":{"type":["number","null"],"description":"Price per month when billed monthly, USD."}},"required":["id","name","credits_included","per_month_annual","monthly"]},"UsageEstimatePacks":{"type":"object","properties":{"credits":{"type":"integer","description":"Extra credits bought: usd × the plan's credits per dollar."},"count":{"type":"integer","description":"Always 1: one purchase covers any self-serve shortfall. Kept for compatibility."},"usd":{"type":"number","description":"What they cost: the shortfall in whole US dollars at the plan rate, rounded up, at least the $10 minimum."}},"required":["credits","count","usd"]},"UsageEstimateOffer":{"type":"object","properties":{"percent_off":{"type":"number"},"months":{"type":"integer"},"price_per_month":{"type":"number","description":"The annual per-month price with the beta thank-you discount applied, USD."}},"required":["percent_off","months","price_per_month"]},"UsageEstimate":{"type":"object","properties":{"object":{"type":"string","enum":["usage_estimate"]},"period":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"],"description":"The window actually priced, as ISO timestamps. `to` is exclusive, and never runs past the moment of the request: a window ending today ends now rather than at tomorrow's midnight, so `credits.per_month` divides only by time that has elapsed."},"schedule_version":{"type":"integer","description":"Version of the credit schedule this estimate prices at."},"credits":{"type":"object","properties":{"charged":{"type":"integer"},"nominal":{"type":"integer"},"beta_free":{"type":"integer"},"per_month":{"type":"object","properties":{"charged":{"type":"integer"},"nominal":{"type":"integer"},"beta_free":{"type":"integer"}},"required":["charged","nominal","beta_free"],"description":"The same three totals scaled to a 30-day month. `plan_for`, `packs_needed`, `above_self_serve` and `offer` are all derived from these, because a pooled monthly allowance can only be compared to a monthly figure."}},"required":["charged","nominal","beta_free","per_month"]},"requests":{"type":"object","properties":{"total":{"type":"integer"},"unrouted":{"type":"integer"},"unmapped":{"type":"integer"}},"required":["total","unrouted","unmapped"]},"by_action":{"type":"array","items":{"$ref":"#/components/schemas/UsageEstimateAction"}},"unmapped":{"type":"array","items":{"$ref":"#/components/schemas/UsageEstimateUnmapped"}},"plan_for":{"anyOf":[{"$ref":"#/components/schemas/UsageEstimatePlan"},{"type":"null"}],"description":"Smallest plan whose pooled credits (plus extra credits bought at its rate) cover `credits.per_month.charged` AND that is entitled to every action the org called. A 30-day projection, not a quote. Null when the traffic is above the self-serve ceiling."},"packs_needed":{"anyOf":[{"$ref":"#/components/schemas/UsageEstimatePacks"},{"type":"null"}],"description":"Extra credits the landing plan needs on top of its pool to cover the projected month, priced as one whole-dollar purchase at the plan rate. Null when the pool already covers it — only the largest plan reaches this."},"above_self_serve":{"type":"boolean","description":"True when the projected month exceeds what the plan ladder plus extra credits sells, and the right next step is a conversation rather than a checkout. `plan_for` is then null."},"offer":{"anyOf":[{"$ref":"#/components/schemas/UsageEstimateOffer"},{"type":"null"}]},"coverage":{"type":"object","properties":{"pre_cutover_unmetered_actions":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["pre_cutover_unmetered_actions","note"]},"request_id":{"type":"string"}},"required":["object","period","schedule_version","credits","requests","by_action","unmapped","plan_for","packs_needed","above_self_serve","offer","coverage","request_id"]},"StripeCheckoutSessionResponse":{"type":"object","properties":{"checkout_url":{"type":["string","null"]},"session_id":{"type":"string"},"request_id":{"type":"string"}},"required":["checkout_url","session_id","request_id"]},"StripeCheckoutSessionStatusResponse":{"type":"object","properties":{"id":{"type":"string","description":"Stripe Checkout Session id."},"kind":{"type":"string","enum":["subscription","pack"],"description":"What the session buys: a subscription, or credits (`pack`, the historical wire value)."},"status":{"type":"string","enum":["open","settled","expired","unpaid"],"description":"open: not settled yet (still payable, or paid and awaiting the webhook). settled: the purchase is recorded. expired: timed out unpaid, nothing charged. unpaid (credit purchases): finished with a delayed payment method; credits land once funds settle."},"settled_at":{"type":["string","null"],"format":"date-time","description":"Credit purchases: when the credits were granted. Subscriptions: when the plan changed. Null until settled."},"credits_granted":{"type":["integer","null"],"description":"Credit purchases: the add-on credits granted. Subscriptions: this checkout's plan grant once invoice.paid has written it. Null until then."},"plan":{"type":["string","null"],"description":"Subscriptions: the organization plan after the webhook. Null for credit purchases and until settled."},"request_id":{"type":"string"}},"required":["id","kind","status","settled_at","credits_granted","plan","request_id"]},"StripeBillingPortalResponse":{"type":"object","properties":{"portal_url":{"type":"string"},"session_id":{"type":"string"},"already_cancelling":{"type":"boolean","description":"True when `subscription_cancel` found the plan already set to cancel: no portal session was opened (`portal_url` is the return URL, `session_id` empty) and the cancellation is now the customer's own."},"request_id":{"type":"string"}},"required":["portal_url","session_id","already_cancelling","request_id"]},"StripePlanChangeResponse":{"type":"object","properties":{"outcome":{"type":"string","enum":["applied","pending_payment","scheduled"],"description":"applied: Stripe applied the change (the proration invoice was paid, or nothing was owed); the plan and credits follow through the webhooks within seconds. Also the answer when the request undid a change scheduled here (the current plan and interval were requested): the schedule is released and nothing is charged. pending_payment: the proration payment failed or needs authentication, so nothing changed yet — the customer pays hosted_invoice_url; paying applies the change, and after about 23 hours unpaid Stripe voids the invoice and drops it. scheduled: a downgrade or a shorter interval takes effect at the current period end (effective_at); nothing is charged now."},"plan":{"type":"string","description":"The target plan (canonical name).","example":"growth"},"interval":{"type":"string","enum":["monthly","annual"],"description":"The target billing interval."},"hosted_invoice_url":{"type":["string","null"],"description":"pending_payment only: the Stripe-hosted page to pay the proration invoice on. Null otherwise."},"expires_at":{"type":["string","null"],"format":"date-time","description":"pending_payment only: when Stripe voids the unpaid invoice and drops the change. Null otherwise."},"effective_at":{"type":["string","null"],"format":"date-time","description":"scheduled only: when the new plan takes over (the current period end). Null otherwise."},"request_id":{"type":"string"}},"required":["outcome","plan","interval","hosted_invoice_url","expires_at","effective_at","request_id"]},"StripeCreditPurchaseCheckoutResponse":{"type":"object","properties":{"checkout_url":{"type":["string","null"]},"session_id":{"type":"string"},"amount_usd":{"type":"integer","description":"Whole US dollars charged, tax-exclusive."},"amount_cents":{"type":"integer","description":"Tax-exclusive price in USD cents (amount_usd × 100)."},"credits":{"type":"integer","description":"Credits granted on settlement (amount_usd × credits_per_usd)."},"credits_per_usd":{"type":"integer","description":"The organization plan's rate at purchase time."},"plan":{"type":"string","description":"The canonical plan the rate was taken from."},"request_id":{"type":"string"}},"required":["checkout_url","session_id","amount_usd","amount_cents","credits","credits_per_usd","plan","request_id"]},"AutoTopUpConfigResponse":{"type":"object","properties":{"enabled":{"type":"boolean"},"needs_reconfiguration":{"type":["string","null"],"enum":["plan_ineligible","sku_not_available_for_plan","no_refill_mode","spend_cap_below_pack_price",null],"description":"Non-null when the stored config is enabled but can never fire as stored, so it is effectively off until updated: plan_ineligible (the organization plan cannot buy credits), sku_not_available_for_plan (refill_sku is another plan's refill unit; it is never switched automatically), no_refill_mode (neither refill_sku nor refill_to_credits is set) or spend_cap_below_pack_price (monthly_spend_cap_usd is below the price of the organization plan's refill unit, so no refill fits; the plan changed after the config was saved, or a pre-cutover config has no cap). Null for a disabled config or an enabled one that can fire."},"threshold_credits":{"type":"integer"},"refill_to_credits":{"type":["integer","null"]},"refill_sku":{"type":["string","null"],"enum":["pack_5k","pack_25k","pack_100k",null],"description":"Fixed refill unit bought per refill (the organization plan's refill unit), or null when refilling to refill_to_credits."},"monthly_spend_cap_usd":{"type":"integer"},"saved_payment_method":{"type":["string","null"]},"month_to_date_spend_usd":{"type":"number"},"last_failure_reason":{"type":["string","null"]},"suspended":{"type":"boolean","description":"True while auto-top-up charging is suspended fleet-wide (all Signa payments run through Stripe Managed Payments, which cannot make automatic off-session charges). While true, any update whose merged result would be enabled is refused with 501."},"request_id":{"type":"string"}},"required":["enabled","needs_reconfiguration","threshold_credits","refill_to_credits","refill_sku","monthly_spend_cap_usd","saved_payment_method","month_to_date_spend_usd","last_failure_reason","suspended","request_id"]},"NotificationCategory":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"}},"required":["key","title","description","enabled"]},"NotificationPreferences":{"type":"object","properties":{"object":{"type":"string","enum":["notification_preferences"]},"org_id":{"type":"string","example":"orgn_abc"},"preferences":{"type":"object","properties":{"credit_usage_alerts":{"type":"boolean","description":"Alerts at 90% and 100% of monthly plan credits."},"watch_credit_notifications":{"type":"boolean","description":"Grace-period reminders and watches-resumed notices."},"auto_topup_receipts":{"type":"boolean","description":"Receipts for successful credit top-ups."}},"required":["credit_usage_alerts","watch_credit_notifications","auto_topup_receipts"]},"categories":{"type":"array","items":{"$ref":"#/components/schemas/NotificationCategory"},"description":"Per-category metadata (title + description + current state) for rendering the settings toggle list. Mandatory notices (final grace warning, watches paused, top-up/payment failures) are not listed — they always send."},"request_id":{"type":"string"}},"required":["object","org_id","preferences","categories","request_id"]},"CreditGrantBreakdown":{"type":"object","properties":{"plan":{"type":"integer","description":"Remaining credits from plan grants."},"addon":{"type":"integer","description":"Remaining credits from addon grants."},"promo":{"type":"integer","description":"Remaining credits from promotional grants."}},"required":["plan","addon","promo"]},"CreditExpiryScheduleEntry":{"type":"object","properties":{"grant_id":{"type":"string","example":"grant_01kpj..."},"type":{"type":"string","enum":["plan","addon","promo"]},"amount":{"type":"integer","description":"Credits originally granted (gross; revoked credits are not subtracted)."},"revoked":{"type":"integer","description":"Credits taken back from this grant after a refund or dispute (0 when none). They are not spent: credits the organization used = amount − revoked − remaining, and amount − revoked is what it could use."},"remaining":{"type":"integer","description":"Credits still usable on this grant (may be negative under debt)."},"pending":{"type":"integer","description":"This grant's share of the top-level `pending`: billable spend not yet attributed by the hourly applier that it will charge to this grant (0 when none). Spend charged to grants that have since ended, or made while no grant was active, is the only part of `pending` not in any entry. Credits still usable on this grant in real time = remaining − pending."},"effective_at":{"type":"string","description":"When the grant became usable (ISO 8601)."},"expires_at":{"type":"string","description":"When the grant expires (ISO 8601, exclusive)."}},"required":["grant_id","type","amount","revoked","remaining","pending","effective_at","expires_at"]},"CreditBalance":{"type":"object","properties":{"object":{"type":"string","enum":["credit_balance"]},"balance":{"type":"integer","description":"Authoritative spendable pooled balance = Σgrants − reserved − pending. May be negative under the D11 floor."},"grants":{"$ref":"#/components/schemas/CreditGrantBreakdown"},"reserved":{"type":"integer","description":"Credits held by open reservations (reserved but not yet settled/refunded)."},"pending":{"type":"integer","description":"Billable spend not yet attributed to specific grants by the hourly applier."},"expiry_schedule":{"type":"array","items":{"$ref":"#/components/schemas/CreditExpiryScheduleEntry"},"description":"Active grants in consumption order (plan first, then oldest-expiry-first)."},"subscription":{"allOf":[{"$ref":"#/components/schemas/SubscriptionSummary"},{"description":"The organization's subscription as Signa mirrors it: status, a scheduled cancellation, the open dunning record while a subscription payment has failed or needs action, and a plan change scheduled for the period end. The same object is returned as `subscription` by GET /v1/organization/credits and GET /v1/organization/me; the dashboard's billing page renders its banner from it. Nothing about entitlement is decided from it."}]}},"required":["object","balance","grants","reserved","pending","expiry_schedule"]},"CreditBalanceResponse":{"allOf":[{"$ref":"#/components/schemas/CreditBalance"},{"type":"object","properties":{"request_id":{"type":"string"}},"required":["request_id"]}]},"CreditPrice":{"type":"object","properties":{"object":{"type":"string","enum":["credit_price"]},"id":{"type":"string"},"name":{"type":"string"},"group":{"type":"string"},"credits":{"type":"integer","minimum":0},"unit":{"type":"string","enum":["per_request","per_page","per_record","per_item","per_screen","per_mark_per_day","per_watch_per_day"],"description":"What one charge of `credits` buys. `read` is `per_request`: one record, or one page of a list or sub-resource; its batch lookup endpoint carries `unit: per_record`. An operation's own `x-signa-credits.unit` in the OpenAPI document can be finer (`per_page` on a list, `per_record` on a detail read): the charge is the same."},"min_plan":{"type":"string","enum":["free","starter","growth","scale","enterprise"]},"status":{"type":"string","enum":["available","beta","planned"]},"required_scope":{"type":"string","description":"Non-default scope shared by every published endpoint in this row, when they all agree. See endpoints[].required_scope for mixed-scope rows. Admin also grants access."},"endpoints":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PATCH","PUT","DELETE"]},"path":{"type":"string","description":"Concrete OpenAPI path with parameters in braces."},"required_scope":{"type":["string","null"],"description":"Effective endpoint scope when different from the default trademarks:read. Null means no single scope is required; see any_authenticated for any valid key or required_scope_any_of for alternatives. Admin also grants access."},"any_authenticated":{"type":"boolean","enum":[true],"description":"Any authenticated API key is accepted, including keys with no scopes. Present with required_scope: null and without required_scope_any_of."},"required_scope_any_of":{"type":"array","items":{"type":"string"},"description":"Accepts any one of these scopes instead of a single required_scope. Admin also grants access."},"unit":{"type":"string","enum":["per_request","per_page","per_record","per_item","per_screen","per_mark_per_day","per_watch_per_day"],"description":"Present when this operation is charged in a different unit than the row: POST /v1/trademarks/batch is per_record (one charge per submitted identifier, including those returned in not_found) on the per_request read row."}},"required":["method","path"]},"description":"Operations published in this deployment; may be empty for daily meters and for actions whose routes are not yet enabled. Identify daily meters by unit (per_mark_per_day or per_watch_per_day), not by an empty array. If the OpenAPI document cannot be built, normalized fixture paths are returned for that request."}},"required":["object","id","name","group","credits","unit","min_plan","status","endpoints"]},"CreditPricingResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CreditPrice"}},"has_more":{"type":"boolean","enum":[false]},"pagination":{"type":"object","properties":{"cursor":{"type":"null"}},"required":["cursor"]},"schedule_version":{"type":"integer"},"degraded":{"type":"boolean","description":"True when the OpenAPI document could not be built and endpoints use normalized fixture paths. The next request retries the build."},"request_id":{"type":"string"}},"required":["object","data","has_more","pagination","schedule_version","degraded"]}},"parameters":{}},"paths":{"/health/live":{"get":{"operationId":"healthLive","tags":["Health"],"security":[],"description":"Liveness probe — returns 200 if the process is running.","responses":{"200":{"description":"Liveness probe","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"required":["status"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health/ready":{"get":{"operationId":"healthReady","tags":["Health"],"security":[],"description":"Readiness probe — checks PostgreSQL, Valkey, and OpenSearch connectivity.","responses":{"200":{"description":"All systems operational or degraded (non-critical dep down)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","unhealthy","shutting_down"]},"service":{"type":"string","enum":["core-api"]},"uptime_ms":{"type":"number"},"dependencies":{"type":"object","properties":{"postgres":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"latency_ms":{"type":"number"}},"required":["status"]},"valkey":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"latency_ms":{"type":"number"}},"required":["status"]},"opensearch":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"latency_ms":{"type":"number"}},"required":["status"]}},"required":["postgres","valkey","opensearch"]}},"required":["status","service","uptime_ms","dependencies"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Unhealthy (critical dep down) or shutting down","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded","unhealthy","shutting_down"]},"service":{"type":"string","enum":["core-api"]},"uptime_ms":{"type":"number"},"dependencies":{"type":"object","properties":{"postgres":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"latency_ms":{"type":"number"}},"required":["status"]},"valkey":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"latency_ms":{"type":"number"}},"required":["status"]},"opensearch":{"type":"object","properties":{"status":{"type":"string","enum":["ok","error"]},"latency_ms":{"type":"number"}},"required":["status"]}},"required":["postgres","valkey","opensearch"]}},"required":["status","service","uptime_ms","dependencies"]}}}}}}},"/health":{"get":{"operationId":"healthRoot","tags":["Health"],"security":[],"description":"Simple health check — returns 200 if the process is running (alias for /health/live).","responses":{"200":{"description":"Health check","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"required":["status"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/health":{"get":{"operationId":"healthV1","tags":["Health"],"security":[],"description":"Simple health check under /v1 prefix (alias for /health).","responses":{"200":{"description":"Health check","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"required":["status"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/healthz":{"get":{"operationId":"healthCheck","tags":["Health"],"security":[],"description":"Legacy health check endpoint (use /health/ready instead).","responses":{"200":{"description":"Health check response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"timestamp":{"type":"string"},"service":{"type":"string"}},"required":["status","timestamp","service"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/offices/votes":{"get":{"operationId":"listOfficeVotes","tags":["Reference Data"],"description":"List the authenticated organization's office-coverage votes, alphabetical by office code. The set is bounded by the votable vocabulary, so the list is always a single page: `limit` and `cursor` are accepted for list-client compatibility but do not affect the response, which always returns every vote with `has_more: false`.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Accepted for list-client compatibility and ignored — the list is single-page."},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Accepted for list-client compatibility and ignored — the list is single-page."},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of office votes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficeVoteList"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}},"post":{"operationId":"castOfficeVotes","tags":["Reference Data"],"description":"Vote for trademark offices your organization wants on Signa. One vote per office per organization — re-votes are no-ops, so the call is safely retryable. Returns the stored votes for every requested code (newly cast or pre-existing).\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 0 per request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"office_codes":{"type":"array","items":{"type":"string","maxLength":64},"minItems":1,"maxItems":50,"description":"Office codes to vote for (1–50). ST.3 / ISO country codes, any case (surrounding whitespace is trimmed); legacy internal codes and reserved aliases like UK are canonicalized. Offices Signa already covers are rejected — vote for what you want added. Codes your organization already voted for are no-ops, never double counts.","example":["BR","MX"]}},"required":["office_codes"],"additionalProperties":false}}}},"responses":{"200":{"description":"Stored votes for the requested codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficeVoteList"}}}},"400":{"description":"Unknown, already-covered, or register-less office code (unknown_office_code / office_already_live / no_trademark_register)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"x-signa-credits":{"credits":0,"unit":"per_request","action":"feedback","status":"available"}}},"/v1/offices/votes/{code}":{"delete":{"operationId":"retractOfficeVote","tags":["Reference Data"],"description":"Retract your organization's vote for an office. Accepts the same code vocabulary as casting; votes for offices that have since gone live can still be retracted.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 0 per request.","parameters":[{"schema":{"type":"string","maxLength":64,"description":"Office code (ST.3 / ISO, any accepted alias).","example":"BR"},"required":true,"name":"code","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"200":{"description":"Vote deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficeVoteDeleted"}}}},"400":{"description":"Unknown office code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No vote for this office","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"feedback","status":"available"}}},"/v1/classifications":{"get":{"operationId":"listClassifications","tags":["Classification"],"description":"List all Nice classification classes, optionally filtered by type or title search.\n\nCredits: 1 per request.","parameters":[{"schema":{"type":"string","enum":["goods","services"],"description":"Filter by category: goods (classes 1-34) or services (classes 35-45)"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Search classification titles (case-insensitive contains)"},"required":false,"name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100,"description":"Max results per page (default: 100, max: 500)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor — opaque value returned in `pagination.cursor` of the previous page"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of Nice classifications","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassificationListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_request","action":"class_lookup","status":"available"}}},"/v1/goods-services":{"get":{"operationId":"listGoodsServices","tags":["Classification"],"description":"Browse/search the aggregated goods & services term catalog (Harmonised Database + USPTO ID Manual). At least one of `q` or `class` is required. Pass `class` to scope to one Nice class, or `q` to substring-search across all classes — or both.\n\nCredits: 1 per request.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":200,"description":"Substring search across term text (2-200 characters). Optional if `class` is provided."},"required":false,"name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":45,"description":"Nice class number (1-45). Optional if `q` is provided."},"required":false,"name":"class","in":"query"},{"schema":{"type":"string","maxLength":10,"default":"en","description":"Language code (default: en)"},"required":false,"name":"language","in":"query"},{"schema":{"type":["boolean","null"],"default":false,"description":"Only return terms on a harmonised list (the EUIPO Harmonised Database, or a USPTO ID Manual entry marked TM5-harmonised). Not a per-office acceptance statement: check accepted_offices."},"required":false,"name":"harmonised_only","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Max results (default: 20, max: 100)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor — opaque value returned in `pagination.cursor` of the previous page"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of matching G&S terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsServicesTermListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Specified class not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_request","action":"class_lookup","status":"available"}}},"/v1/classifications/{classNumber}":{"get":{"operationId":"retrieveClassification","tags":["Classification"],"description":"Retrieve a single Nice classification with its terms.\n\nCredits: 1 per request.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":45,"description":"Nice class number (1-45)"},"required":true,"name":"classNumber","in":"path"}],"responses":{"200":{"description":"Single Nice classification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassificationDetailResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_request","action":"class_lookup","status":"available"}}},"/v1/classifications/suggest":{"post":{"operationId":"suggestClassifications","tags":["Classification"],"description":"Suggest Nice classification classes for a natural-language description. Returns ranked classes with confidence and rationale. For filing-ready goods/services wording per class, use POST /v1/goods-services/suggest.\n\nCredits: 10 per request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":3,"maxLength":500,"description":"Natural-language description of goods, services, or business (3-500 chars).","example":"e-commerce company selling sneakers"}},"required":["description"],"additionalProperties":false}}}},"responses":{"200":{"description":"Ranked Nice classification suggestions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassificationSuggestionResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream classification service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_request","action":"class_suggest","status":"available"}}},"/v1/goods-services/suggest":{"post":{"operationId":"suggestGoodsServices","tags":["Classification"],"description":"Draft a goods/services specification for a natural-language description. Returns ranked Nice classes with filing-ready goods/services wording per class, grounded in the pre-approved term catalog (Harmonised Database + USPTO ID Manual). Pass `class_number` to restrict the response to a single, already-chosen class.\n\nCredits: 100 per request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":3,"maxLength":500,"description":"Natural-language description of goods, services, or business (3-500 chars).","example":"e-commerce company selling sneakers"},"jurisdiction_code":{"type":"string","minLength":2,"maxLength":2,"description":"Optional ISO-3166-1 alpha-2 jurisdiction code to bias retail-vs-product interpretation.","example":"US"},"class_number":{"type":"integer","minimum":1,"maximum":45,"description":"Optional Nice class (1-45). When set, only goods/services wording for this class is returned — useful for refining wording when the class has already been chosen.","example":25}},"required":["description"],"additionalProperties":false}}}},"responses":{"200":{"description":"Goods/services suggestion — ranked classes with grounded accepted terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsServicesSuggestionResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream classification service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":100,"unit":"per_request","action":"gs_draft","status":"available"}}},"/v1/goods-services/validate":{"post":{"operationId":"validateGoodsServices","tags":["Classification"],"description":"Check goods & services wording against the pre-approved catalogs we hold (EUIPO Harmonised Database + USPTO ID Manual), per office and per Nice class. Returns one row per submitted item, in request order, with a per-office verdict and — when the wording is not listed and a class is known — nearby catalogued wording to draft from.\n\n`listed` means the wording appears in that office’s pre-approved catalog, exactly or after punctuation normalization (see `match.type`). `not_listed` means we cannot show it there: those catalogs are pre-approval shortcuts, not exhaustive lists of acceptable wording, so a `not_listed` term is NOT a refusal and not a prediction of one. `unsupported_office` means we hold no catalog for that office at all.\n\nCredits: 50 per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsServicesValidateRequest"}}}},"responses":{"200":{"description":"One validation row per submitted item, plus a leading `summary` block.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoodsServicesValidationListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited or out of quota","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"x-signa-credits":{"credits":50,"unit":"per_request","action":"gs_validate","status":"available"}}},"/v1/offices":{"get":{"operationId":"listOffices","tags":["Reference Data"],"description":"List all supported trademark offices with sync metadata.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100,"description":"Max results per page (default: 100, max: 500)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor — opaque value returned in `pagination.cursor` of the previous page"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of trademark offices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficeListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/offices/{code}":{"get":{"operationId":"retrieveOffice","tags":["Reference Data"],"description":"Retrieve a single trademark office with sync metadata and connector details.","parameters":[{"schema":{"type":"string","description":"Office code as returned by `GET /v1/offices` — the WIPO ST.3 code, any case (e.g. `US`, `EM`, `WO`, `se`). Legacy internal codes (`uspto`, `euipo`, `prv`, ...) and the `EU` alias for EUIPO are accepted permanently. This is **not** the jurisdiction code — use `/v1/jurisdictions/{code}` for ISO country codes.","example":"US"},"required":true,"name":"code","in":"path"}],"responses":{"200":{"description":"Single office","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficeDetailResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jurisdictions":{"get":{"operationId":"listJurisdictions","tags":["Reference Data"],"description":"List all supported jurisdictions.","parameters":[{"schema":{"type":["boolean","null"],"description":"If true, returns total_count in the pagination object."},"required":false,"name":"include_total","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100,"description":"Max results per page (default: 100, max: 500)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor — opaque value returned in `pagination.cursor` of the previous page"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of jurisdictions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JurisdictionListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jurisdictions/{code}":{"get":{"operationId":"retrieveJurisdiction","tags":["Reference Data"],"description":"Retrieve a single jurisdiction with Madrid membership details.","parameters":[{"schema":{"type":"string","description":"Jurisdiction code (e.g. US, EU, GB)"},"required":true,"name":"code","in":"path"}],"responses":{"200":{"description":"Single jurisdiction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JurisdictionDetailResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/deadline-rules":{"get":{"operationId":"listDeadlineRules","tags":["Deadlines"],"description":"List all deadline rules across modeled jurisdictions (renewal cycles, declarations of use, restoration, etc.). Rules are self-contained with statutory citations.\n\nCredits: 10 per request.","parameters":[{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by jurisdiction code (ISO 3166-1 alpha-2, `EU`, and `WO` for the Madrid rules), case-insensitive. Office spellings are read as the jurisdiction they cover: `EM` as `EU`, `UK` as `GB`, `WIPO` as `WO`. `madrid_designation_renewal`, listed once under `WO`, is also returned for every jurisdiction whose Madrid designations it serves (a WIPO Madrid designation code without its own rules, and `EU`). A country with no modeled rules returns an empty list; a value that is not a country or jurisdiction code returns 400. Multiple values comma-separated."},"required":false,"name":"jurisdiction","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["national","regional","madrid","direct_national","direct_regional","madrid_ir","madrid_designation"]},"maxItems":100,"description":"Filter by filing route: `national`, `regional` or `madrid`. Four trademark `filing_route` values are accepted as aliases: `direct_national` (read as `national`), `direct_regional` (as `regional`), and `madrid_ir` and `madrid_designation` (as `madrid`). The other trademark values (`transformation`, `divisional`, `unknown`) return 400 with the accepted list. Most rules apply to all routes (appliesTo=null) and are returned for any value."},"required":false,"name":"filing_route","in":"query","style":"form","explode":false}],"responses":{"200":{"description":"Flat list of deadline rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeadlineRuleListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_request","action":"rules_lookup","status":"available"}}},"/v1/opposition-rules":{"get":{"operationId":"listOppositionRules","tags":["Oppositions"],"description":"List all opposition window rules across modeled offices. Each rule includes statutory citations, window duration, and the office time zone.\n\nCredits: 10 per request.","parameters":[{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by jurisdiction code (ISO 3166-1 alpha-2 or `EU`), case-insensitive. Office spellings are read as the jurisdiction they cover: `EM` as `EU`, `UK` as `GB`. A value that is not a country or jurisdiction code returns 400. Multiple values comma-separated."},"required":false,"name":"jurisdiction","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by office code. WIPO ST.3 uppercase (e.g. US, EM); legacy acronym slugs (uspto, euipo) and EU are also accepted. Multiple values comma-separated."},"required":false,"name":"office","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["domestic","madrid_designation","direct_national","direct_regional"]},"maxItems":100,"description":"Filter by filing route discriminator on the rule: `domestic` or `madrid_designation`. Two trademark `filing_route` values are accepted as aliases of `domestic`: `direct_national` and `direct_regional`. The other trademark values (`madrid_ir`, `transformation`, `divisional`, `unknown`) return 400 with the accepted list."},"required":false,"name":"filing_route","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["application_publication","registration_publication","international_designation_publication"]},"maxItems":100,"description":"Filter by trigger event."},"required":false,"name":"trigger_event","in":"query","style":"form","explode":false}],"responses":{"200":{"description":"Flat list of opposition rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OppositionRuleListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_request","action":"rules_lookup","status":"available"}}},"/v1/prosecution-rules":{"get":{"operationId":"listProsecutionRules","tags":["Deadlines"],"description":"List all prosecution deadline rules (office-action responses, suspension inquiries, statements of use) across modeled offices. Rules are self-contained with statutory citations, verbatim quoted text, extension ladders, era boundaries and remedies. Every `rule.rule_id` cited by a computed prosecution deadline on `POST /v1/deadlines/compute` resolves to exactly one row of this catalog.\n\nCredits: 10 per request.","parameters":[{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by jurisdiction code (ISO 3166-1 alpha-2 or `EU`), case-insensitive. Office spellings are read as the jurisdiction they cover: `EM` as `EU`, `UK` as `GB`. A country with no modeled rules returns an empty list; a value that is not a country or jurisdiction code returns 400. Multiple values comma-separated."},"required":false,"name":"jurisdiction","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by office code. WIPO ST.3 uppercase (e.g. US, EM); legacy acronym slugs (uspto, euipo) and EU are also accepted. An unknown office code returns 400. Multiple values comma-separated."},"required":false,"name":"office","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["national","regional","madrid","direct_national","direct_regional","madrid_ir","madrid_designation"]},"maxItems":100,"description":"Filter by filing route, in the `POST /v1/deadlines/compute` vocabulary: `national` and `regional` select `direct_national` rules, `madrid` selects `madrid_designation` rules. As on `GET /v1/deadline-rules`, four trademark `filing_route` values are accepted as aliases: `direct_national` (read as `national`), `direct_regional` (as `regional`), and `madrid_ir` and `madrid_designation` (as `madrid`). Rules with `route: any` apply to every route and are returned for any value."},"required":false,"name":"filing_route","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["oa_response","suspension_inquiry_response","post_registration_oa_response","sou"]},"maxItems":100,"description":"Filter by prosecution deadline type, in the `support[].type` vocabulary of `POST /v1/deadlines/compute`."},"required":false,"name":"deadline_type","in":"query","style":"form","explode":false}],"responses":{"200":{"description":"Flat list of prosecution deadline rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProsecutionRuleListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_request","action":"rules_lookup","status":"available"}}},"/v1/event-types":{"get":{"operationId":"listEventTypes","tags":["Reference Data"],"description":"List the office event codes Signa has catalogued and the canonical `event_type` each maps to. The catalogue covers the USPTO (`US`), IP Australia (`AU`) and WIPO (`WO`) today; any other office returns an empty list, and its trademark events still carry their own `raw` code and label. `raw` is the office's verbatim code and label, as on a trademark event's `raw` (label null when we hold no verbatim office label for the code; every WIPO label is null because the catalogue's WIPO wording is Signa's).","parameters":[{"schema":{"type":"string","description":"Filter by office code (the rows' `office_code`). WIPO ST.3 uppercase (e.g. US, EM); legacy acronym slugs (uspto, euipo) and EU are also accepted. Unknown query parameters are rejected with 400."},"required":false,"name":"office_code","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100,"description":"Max results per page (default: 100, max: 500)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor — opaque value returned in `pagination.cursor` of the previous page"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of event types","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventTypeListResponse"}}}},"400":{"description":"Unknown office code or query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/status-codes":{"get":{"operationId":"listStatusCodes","tags":["Reference Data"],"description":"List office status codes: the office's verbatim code and label (`raw`, as on a trademark's `status.raw`) and the canonical `primary`/`stage`/`reason` Signa maps it to. `raw.label` is null when we hold no verbatim office label for the code (for example USPTO codes today).","parameters":[{"schema":{"type":"string","description":"Filter by office code (the rows' `office_code`). WIPO ST.3 uppercase (e.g. US, EM); legacy acronym slugs (uspto, euipo) and EU are also accepted. Unknown query parameters are rejected with 400."},"required":false,"name":"office_code","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100,"description":"Max results per page (default: 100, max: 500)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor — opaque value returned in `pagination.cursor` of the previous page"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of office status codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusCodeListResponse"}}}},"400":{"description":"Unknown office code or query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/design-codes":{"get":{"operationId":"listDesignCodes","tags":["Reference Data"],"description":"List Vienna classification design codes. Optional search by description, filter by depth (1-3) or category.\n\nCredits: 1 per request.","parameters":[{"schema":{"type":"string","maxLength":200,"description":"Search descriptions (case-insensitive contains)"},"required":false,"name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":3,"description":"Filter by depth level (1=category, 2=division, 3=section)"},"required":false,"name":"depth","in":"query"},{"schema":{"type":"string","maxLength":10,"description":"Filter by 2-digit category code (e.g. \"03\")"},"required":false,"name":"category","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100,"description":"Max results (default: 100, max: 500)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor (code of last item)"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of Vienna classification codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignCodeListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_request","action":"class_lookup","status":"available"}}},"/v1/design-codes/{code}":{"get":{"operationId":"retrieveDesignCode","tags":["Reference Data"],"description":"Retrieve a single Vienna classification code with notes and children at the next depth level.\n\nCredits: 1 per request.","parameters":[{"schema":{"type":"string","description":"Vienna classification code, zero-padded. Accepts any depth: `01` (category), `01.01` (division), `01.01.01` (section). Also accepts the undotted form `010101`. Call `GET /v1/design-codes` for the full tree.","example":"01.01.01"},"required":true,"name":"code","in":"path"}],"responses":{"200":{"description":"Single design code with children","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignCodeDetailResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_request","action":"class_lookup","status":"available"}}},"/v1/trademarks/search/image":{"post":{"operationId":"searchTrademarksByImage","tags":["Trademarks"],"description":"INTERNAL/alpha — requires the `image-search:read` scope (internal + design-partner keys only until GA). Search trademarks by logo/image similarity. Accepts a multipart `image` upload, an `{image_url}` (https, SSRF-guarded), or a `{media_id}` (reuse an existing mark logo). Returns mark-level hits with named signal channels + thumbnails. Metered as `image_search`, at the price generated below, which is not charged while the image index is being built. Zero-billed calls report `X-Credits-Charged: 0` and omit the `X-Credits-Limit`, `X-Credits-Remaining` and `X-Credits-Reset` balance headers (nothing is debited); see the credit headers section of the rate limits guide. Bounded top-K (limit ≤ 100). The query image is never stored.\n\nCredits: 100 per request. Planned price; not currently charged.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchBody"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ImageSearchMultipart"}}}},"responses":{"200":{"description":"Ranked image-search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Unsupported media type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream (image fetch/analysis) error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Image search backend unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":100,"unit":"per_request","action":"image","status":"planned"}}},"/v1/trademarks/image-thumbnails/{imageId}":{"get":{"operationId":"getImageThumbnail","tags":["Trademarks"],"description":"Proxy serving the 256px WebP thumbnail for an image-search hit. Unauthenticated — suitable for <img> tags.","security":[],"parameters":[{"schema":{"type":"string","description":"Image ID (img_…)"},"required":true,"name":"imageId","in":"path"}],"responses":{"200":{"description":"WebP thumbnail"},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Thumbnail not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Storage unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trademarks/{id}":{"get":{"operationId":"retrieveTrademark","tags":["Trademarks"],"description":"Retrieve a single trademark by ID with full detail tier (all bounded children inline, computed deadlines, data freshness). Pass language to prefer that goods/services language on records that carry per-language classification variants (direct and Madrid designation records) when multiple variants exist for the same Nice class; groups without the requested language — and IR-parent rollup classifications, which have no per-language variants — keep the default classification ordering.\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","description":"Trademark ID (tm_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["office_extensions"]},"maxItems":100,"description":"Comma-separated optional detail projections. `office_extensions` includes raw office-specific blobs."},"required":false,"name":"include","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Sparse top-level field projection. Comma-separated field names; id and object are always retained. Fields you do not request are omitted, although the response schema lists every field."},"required":false,"name":"fields","in":"query","style":"form","explode":false},{"schema":{"type":"string","minLength":2,"maxLength":6,"pattern":"^[A-Za-z]{2,3}(-[A-Za-z]{2})?$","description":"Preferred goods/services language, applied only to records that carry per-language classification variants (direct and Madrid designation records). IR-parent rollup classifications have no per-language variants and are unaffected. 2-3 letter language tag with optional 2-letter region.","example":"en"},"required":false,"name":"language","in":"query"}],"responses":{"200":{"description":"Trademark detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrademarkDetailResponse"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/trademarks/batch":{"post":{"operationId":"batchLookupTrademarks","tags":["Trademarks"],"description":"Batch lookup trademarks by IDs or office-native identifiers. Max 100 items. Returns detail tier per trademark + not_found array. Billed per submitted identifier, including the ones returned in not_found.\n\nCredits: 1 per record.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrademarkBatchRequest"}}}},"responses":{"200":{"description":"Batch lookup results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrademarkBatchResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/trademarks":{"post":{"operationId":"listTrademarksPost","tags":["Trademarks"],"description":"Trademark search: q ranks marks through the similarity channels, filters (filters.mark_text included) decide which marks qualify, exclude removes marks, with faceted aggregations. Without q, acts as a filtered list (requires a filter or a mark_text operator). relevance_score is present on every hit whenever there is a q, whatever the sort.\n\nCredits: 10 per page.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string","maxLength":200},"minItems":1,"maxItems":100}],"description":"Search text, ranked through the similarity channels: 1-500 characters, at least 2 after case and accent folding (one CJK character is enough). Always literal; filter on the mark text with the mark_text operators. A trademark number in q (1939139, US 5123456, tm_...) is also looked up and its records lead the page. Optional for a filtered listing. A list of 1-100 terms (each up to 200 characters, e.g. spelling variants) runs every term through the same similarity channels in one search: a hit ranks by its best term and match.terms names the terms that reached it. A list over 10 terms needs similarity limited to identical and lookalike; with fuzzy, embedded or phonetic a list takes 10 terms and 30 words in total. A list is never read as a trademark number.","example":"SIGNA"},"similarity":{"type":"array","items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"Similarity channels for q: identical, fuzzy, embedded, phonetic, lookalike. Default identical, fuzzy, embedded, lookalike; identical is always on. Requires q."},"exclude":{"$ref":"#/components/schemas/SearchExclude"},"sort":{"type":"string","description":"Sort field(s), comma-separated, - prefix for desc. Default: relevance with q, mark text order with a mark_text filter and no q, otherwise -filing_date. relevance_score stays on every hit under any sort when q is present. sort=office_code orders by the ST.3 code shown in office_code. Valid: filing_date, registration_date, expiry_date, renewal_due_date, updated_at, publication_date, termination_date, office_code, jurisdiction_code, mark_text, owner_name. Max 3."},"territory_match":{"type":"string","enum":["protection","direct"],"description":"How filters.jurisdictions matches: protection (default — includes regional rights whose membership covers the requested territory, e.g. a EUTM for jurisdictions=[FR]) or direct (literal territory legs only)."},"filters":{"type":"object","properties":{"status_primary":{"anyOf":[{"type":"string","enum":["pending","active","inactive","unknown","mixed"]},{"type":"array","items":{"type":"string","enum":["pending","active","inactive","unknown","mixed"]},"maxItems":100}],"description":"Primary status, one value or a list. \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"status_stage":{"type":"array","items":{"type":"string","enum":["filed","examining","pending_publication","published","opposition_period","pending_opposition","pending_cancellation","pending_issuance","registered","allowed","abandoned","withdrawn","surrendered","refused","cancelled","invalidated","expired","unknown","mixed"]},"description":"Status stage(s). \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"status_reason":{"type":"array","items":{"type":"string","enum":["refused","withdrawn","abandoned","cancelled","invalidated","expired","surrendered","revoked","other"]}},"challenge_states":{"type":"array","items":{"type":"string","enum":["opposition_pending","cancellation_pending","invalidation_pending","appeal_pending","court_pending","other_pending"]}},"mark_feature_type":{"type":"array","items":{"type":"string","enum":["word","figurative","combined","three_d","color","sound","motion","hologram","pattern","position","multimedia","scent","taste","texture","other","unknown"]}},"mark_legal_category":{"type":"array","items":{"type":"string","enum":["standard","collective","certification","collective_membership","defensive","guarantee","geographical_indication","other","unknown"]}},"right_kind":{"type":"string","enum":["trademark","trade_name","commercial_notice","geographical_indication","other"]},"filing_route":{"type":"array","items":{"type":"string","enum":["direct_national","direct_regional","madrid_ir","madrid_designation","transformation","divisional","unknown"]}},"scope_kind":{"type":"array","items":{"type":"string","enum":["national","regional","international_registration"]}},"jurisdictions":{"type":"array","items":{"type":"string"}},"offices":{"type":"array","items":{"type":"string"}},"owner_country":{"type":"string"},"nice_classes":{"type":"array","items":{"type":"integer","minimum":1,"maximum":45}},"vienna_codes":{"type":"array","items":{"type":"string"}},"us_design_codes":{"type":"array","items":{"type":"string"}},"filing_basis":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}:[A-Z0-9]+$"},"maxItems":100},"register_type":{"type":"string","minLength":1,"maxLength":64,"description":"Filter by the office register (`register.type`), e.g. principal or supplemental (US) or the CIPO register category (CA). Case-insensitive."},"opposition_status":{"type":"string","enum":["open","not_started","closed","unknown"]},"opposition_closes_gte":{"type":"string","description":"Opposition window closes on or after this date."},"opposition_closes_lte":{"type":"string","description":"Opposition window closes on or before this date."},"seniority_claims":{"type":"string","enum":["claimed","none","unknown"]},"goods_services_text":{"type":"string"},"filing_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"registration_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"expiry_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"renewal_due_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"publication_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"termination_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"status_effective_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"priority_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"designation_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false,"description":"Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"first_use_anywhere_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"first_use_in_commerce_date":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"updated_at":{"type":"object","properties":{"gte":{"type":"string"},"gt":{"type":"string"},"lte":{"type":"string"},"lt":{"type":"string"}},"additionalProperties":false},"owner_id":{"type":"string"},"owner_name":{"type":"string"},"attorney_id":{"type":"string"},"firm_id":{"type":"string"},"attorney_firm_name":{"type":"string"},"entity_id":{"type":"string","description":"Filter by resolved entity (ent_...): marks whose owners are linked to the entity. An owner id written with the entity prefix (ent_<owner-uuid>) is not an entity and matches nothing; use owner_id. Mutually exclusive with entity_group."},"entity_group":{"type":"string","description":"Filter by an entity's whole GLEIF corporate family (ent_...). Mutually exclusive with entity_id."},"application_number":{"type":"string"},"registration_number":{"type":"string"},"ir_number":{"type":"string"},"office":{"type":"string"},"origin_office_code":{"type":"string"},"has_media":{"type":"boolean"},"has_proceedings":{"type":"boolean"},"is_madrid":{"type":"boolean"},"is_retracted":{"type":"boolean"},"is_series_mark":{"type":"boolean"},"owner_publicly_traded":{"type":"boolean","description":"Filter by public trading status. A false/absent value means no confirmed match, NOT confirmed private — owner→company matching covers ~6% of marks."},"owner_has_lei":{"type":"boolean","description":"Filter by LEI presence. A false/absent value means no confirmed match — owner→company matching covers ~6% of marks."},"owner_ticker":{"type":"string","description":"Filter by exact ticker symbol (uppercased server-side)."},"owner_lei":{"type":"string","description":"Filter by exact LEI (uppercased server-side)."},"trademark_ids":{"type":"array","items":{"type":"string","pattern":"^tm_"},"maxItems":1000},"mark_text":{"$ref":"#/components/schemas/MarkTextFilters"}},"additionalProperties":false},"options":{"type":"object","properties":{"aggregations":{"type":"array","items":{"type":"string","enum":["status_stage","office_code","jurisdiction_code","nice_classes","filing_year","mark_feature_type","mark_legal_category","filing_route","right_kind","scope_kind","firm_id","attorney_id","owner_country","owner_id","entity_id","owner_count","entity_count"]}},"aggregation_mode":{"type":"string","enum":["filtered","exclude_own_filter"],"description":"How aggregation counts relate to filters. `filtered` (default): every bucket counts the same filtered set as the results, so buckets add up to `total_count` for single-valued fields. `exclude_own_filter`: each aggregation applies every filter except its own (the `office_code` buckets ignore `offices`, the `nice_classes` buckets ignore `nice_classes`, …), for drill-down sidebars that show the alternatives."},"aggregations_only":{"type":"boolean"},"include_total":{"type":"boolean"},"highlights":{"type":"boolean","description":"If true, includes highlight snippets for a ranked q."},"include_timing":{"type":"boolean"},"allow_partial":{"type":"boolean","description":"Return 200 with search_meta.complete=false when the engine times out or a shard fails, instead of 503. Default false."}},"additionalProperties":false},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20},"cursor":{"type":"string"},"international_registrations":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation. Default grouped → one row per mark/IR, with coverage on IR rows; a trademark number in q returns one row per record it names. Use expanded for one row per Madrid designation.","example":"grouped"},"include":{"type":"array","items":{"type":"string","enum":["full_goods_services","match_details"]},"description":"Optional row projections. `full_goods_services` returns full classifications[].goods_services_text; default rows truncate long G&S text to about 280 characters. `match_details` adds match.details (the matched lanes and the ranking factors applied) to each hit.","example":["full_goods_services"]},"fields":{"type":"array","items":{"type":"string"},"description":"Sparse top-level field projection. id and object are always retained. Fields you do not request are omitted, although the response schema lists every field.","example":["mark_text","status","nice_classes","owners"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponseV2"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Entity too large: the entity_group family-graph walk exceeded its bound (`error.reason` family_graph_too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_page","action":"search","status":"available"}},"get":{"operationId":"listTrademarks","tags":["Trademarks"],"description":"GET variant of trademark search/list. Same search as POST, with flat query params.\n\nCredits: 10 per page.","parameters":[{"schema":{"type":"string","description":"Search text, ranked through the similarity channels: 1-500 characters, at least 2 after case and accent folding (one CJK character is enough). Always literal; filter on the mark text with the mark_text operators. A trademark number in q (1939139, US 5123456, tm_...) is also looked up and its records lead the page. Optional for a filtered listing. A list of 1-100 terms (each up to 200 characters, e.g. spelling variants) runs every term through the same similarity channels in one search: a hit ranks by its best term and match.terms names the terms that reached it. A list over 10 terms needs similarity limited to identical and lookalike; with fuzzy, embedded or phonetic a list takes 10 terms and 30 words in total. A list is never read as a trademark number. On GET send a list as a JSON array (q=[\"limber\",\"bimber\"]). The whole query string must stay under 2 KB (longer ones are rejected with 403 before reaching the API); send long lists with POST."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Sort field(s), comma-separated, - prefix for desc. Default: relevance with q, mark text order with a mark_text filter and no q, otherwise -filing_date. relevance_score stays on every hit under any sort when q is present. sort=office_code orders by the ST.3 code shown in office_code."},"required":false,"name":"sort","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"Similarity channels for q, comma-separated: identical, fuzzy, embedded, phonetic, lookalike. Default identical,fuzzy,embedded,lookalike; identical is always on. Requires q."},"required":false,"name":"similarity","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the whole mark equals the value (case, accents, punctuation, spacing and trademark notices ignored). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_is","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the value appears as a whole word (or consecutive words) of the mark. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_word","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the mark begins with the value (case, accents, punctuation and spacing folded). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_starts_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the mark ends with the value (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_ends_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the value appears anywhere in the mark (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_contains","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where `*` matches any run, `?` one character, `\\` escapes the next character; everything else is literal. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_pattern","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the whole mark equals the value (case, accents, punctuation, spacing and trademark notices ignored). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_is","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the value appears as a whole word (or consecutive words) of the mark. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_word","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the mark begins with the value (case, accents, punctuation and spacing folded). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_starts_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the mark ends with the value (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_ends_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the value appears anywhere in the mark (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_contains","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where `*` matches any run, `?` one character, `\\` escapes the next character; everything else is literal. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_pattern","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks whose owners are linked to these entities (ent_...). Repeat the key for several ids."},"required":false,"name":"entity_id_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks linked to any entity in these entities' corporate families (ent_...). Repeat the key for several ids."},"required":false,"name":"entity_group_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks held by these owners (own_...). Repeat the key for several ids."},"required":false,"name":"owner_id_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude these trademarks (tm_...); on the grouped view, the family row containing them. Up to 1000. Repeat the key for several ids."},"required":false,"name":"trademark_ids_not","in":"query","style":"form","explode":true},{"schema":{"type":["boolean","null"],"description":"Return 200 with search_meta.complete=false when the engine times out or a shard fails, instead of 503. Default false."},"required":false,"name":"allow_partial","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["pending","active","inactive","unknown","mixed"]},"maxItems":100,"description":"Filter by primary status. \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"required":false,"name":"status_primary","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["filed","examining","pending_publication","published","opposition_period","pending_opposition","pending_cancellation","pending_issuance","registered","allowed","abandoned","withdrawn","surrendered","refused","cancelled","invalidated","expired","unknown","mixed"]},"maxItems":100,"description":"Filter by status stage(s). \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"required":false,"name":"status_stage","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["refused","withdrawn","abandoned","cancelled","invalidated","expired","surrendered","revoked","other"]},"maxItems":100,"description":"Filter by status reason(s)."},"required":false,"name":"status_reason","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["opposition_pending","cancellation_pending","invalidation_pending","appeal_pending","court_pending","other_pending"]},"maxItems":100,"description":"Filter by challenge state(s)."},"required":false,"name":"challenge_states","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["word","figurative","combined","three_d","color","sound","motion","hologram","pattern","position","multimedia","scent","taste","texture","other","unknown"]},"maxItems":100,"description":"Filter by mark feature type(s)."},"required":false,"name":"mark_feature_type","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["standard","collective","certification","collective_membership","defensive","guarantee","geographical_indication","other","unknown"]},"maxItems":100,"description":"Filter by mark legal category(s)."},"required":false,"name":"mark_legal_category","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["trademark","trade_name","commercial_notice","geographical_indication","other"]},"required":false,"name":"right_kind","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["direct_national","direct_regional","madrid_ir","madrid_designation","transformation","divisional","unknown"]},"maxItems":100,"description":"Filter by filing route(s)."},"required":false,"name":"filing_route","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["national","regional","international_registration"]},"maxItems":100,"description":"Filter by scope kind(s)."},"required":false,"name":"scope_kind","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by jurisdiction code(s) (UK is read as GB, WIPO as WO). Protection-scope by default: rights that protect, or seek protection, in these territories (a EUTM matches a jurisdictions=FR request). Use territory_match=direct for literal-leg matching."},"required":false,"name":"jurisdictions","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["protection","direct"],"description":"How jurisdictions filters match: protection (default — includes regional rights whose membership covers the requested territory, e.g. a EUTM for jurisdictions=FR) or direct (literal territory legs only)."},"required":false,"name":"territory_match","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by office code(s)."},"required":false,"name":"offices","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Filter by owner country code. Two-letter country code, case-insensitive. Office spellings match too: `EU` and `EM` both match records stored under either, as do `GB` and `UK` (`WIPO` is read as `WO`). Historical codes such as `DD` or `SU` are accepted; an empty value is no filter; a value that is not a two-letter code returns 400 `unknown_country_code`."},"required":false,"name":"owner_country","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"integer"},"maxItems":100,"description":"Filter by Nice class number(s) (1-45)."},"required":false,"name":"nice_classes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by Vienna code(s)."},"required":false,"name":"vienna_codes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by U.S. design search code(s)."},"required":false,"name":"us_design_codes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Z]{2}:[A-Z0-9]+$"},"maxItems":100,"description":"Filter by namespaced filing basis code(s), e.g. US:1A,US:44E."},"required":false,"name":"filing_basis","in":"query","style":"form","explode":false},{"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Filter by the office register (`register.type`), e.g. principal or supplemental (US) or the CIPO register category (CA). Case-insensitive."},"required":false,"name":"register_type","in":"query"},{"schema":{"type":"string","description":"Filter by derived opposition window status: open, not_started, closed, or unknown."},"required":false,"name":"opposition_status","in":"query","style":"form","explode":false},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Opposition window closes on or after this date (YYYY-MM-DD)."},"required":false,"name":"opposition_closes_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Opposition window closes on or before this date (YYYY-MM-DD)."},"required":false,"name":"opposition_closes_lte","in":"query"},{"schema":{"type":"string","description":"Filter by seniority claim state: claimed, none, or unknown."},"required":false,"name":"seniority_claims","in":"query","style":"form","explode":false},{"schema":{"type":"string"},"required":false,"name":"goods_services_text","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"filing_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"filing_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"filing_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"filing_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"registration_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"registration_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"registration_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"registration_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"expiry_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"expiry_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"expiry_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"expiry_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"renewal_due_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"renewal_due_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"renewal_due_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"renewal_due_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"publication_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"publication_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"publication_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"publication_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date on or after (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date after (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date on or before (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date before (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"status_effective_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"status_effective_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"status_effective_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"status_effective_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"priority_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"priority_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"priority_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"priority_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"first_use_anywhere_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"first_use_anywhere_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"first_use_anywhere_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"first_use_anywhere_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"first_use_in_commerce_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"first_use_in_commerce_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"first_use_in_commerce_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"first_use_in_commerce_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"termination_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"termination_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"termination_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"termination_date_lt","in":"query"},{"schema":{"type":"string"},"required":false,"name":"updated_at_gte","in":"query"},{"schema":{"type":"string"},"required":false,"name":"updated_at_gt","in":"query"},{"schema":{"type":"string"},"required":false,"name":"updated_at_lte","in":"query"},{"schema":{"type":"string"},"required":false,"name":"updated_at_lt","in":"query"},{"schema":{"type":"string"},"required":false,"name":"owner_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"owner_name","in":"query"},{"schema":{"type":"string"},"required":false,"name":"attorney_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"firm_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"attorney_firm_name","in":"query"},{"schema":{"type":"string","description":"Filter by resolved entity (ent_...): marks whose owners are linked to the entity, the global cross-office portfolio. An owner id written with the entity prefix (ent_<owner-uuid>) is not an entity and matches nothing; use owner_id. Mutually exclusive with entity_group."},"required":false,"name":"entity_id","in":"query"},{"schema":{"type":"string","description":"Filter by an entity's whole GLEIF corporate family (ent_...): marks linked to any entity in the family (group-level, never identity). Mutually exclusive with entity_id."},"required":false,"name":"entity_group","in":"query"},{"schema":{"type":"string"},"required":false,"name":"application_number","in":"query"},{"schema":{"type":"string"},"required":false,"name":"registration_number","in":"query"},{"schema":{"type":"string"},"required":false,"name":"ir_number","in":"query"},{"schema":{"type":"string"},"required":false,"name":"office","in":"query"},{"schema":{"type":"string"},"required":false,"name":"origin_office_code","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by media presence."},"required":false,"name":"has_media","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by proceedings presence."},"required":false,"name":"has_proceedings","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter Madrid marks."},"required":false,"name":"is_madrid","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter retracted marks."},"required":false,"name":"is_retracted","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter series marks."},"required":false,"name":"is_series_mark","in":"query"},{"schema":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation. Default grouped → one row per mark/IR, with coverage on IR rows; a trademark number in q returns one row per record it names. Use expanded for one row per Madrid designation."},"required":false,"name":"international_registrations","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["full_goods_services","match_details"]},"maxItems":100,"description":"Comma-separated optional row projections. `full_goods_services` returns full classifications[].goods_services_text; default rows truncate long G&S text to about 280 characters. `match_details` adds match.details (the matched lanes and the ranking factors applied) to each hit."},"required":false,"name":"include","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Sparse top-level field projection. Comma-separated field names; id and object are always retained. Fields you do not request are omitted, although the response schema lists every field."},"required":false,"name":"fields","in":"query","style":"form","explode":false},{"schema":{"type":["boolean","null"],"description":"Filter by public trading status. A false/absent value means no confirmed match, NOT confirmed private — owner→company matching covers ~6% of marks."},"required":false,"name":"owner_publicly_traded","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by LEI presence. A false/absent value means no confirmed match — owner→company matching covers ~6% of marks."},"required":false,"name":"owner_has_lei","in":"query"},{"schema":{"type":"string","description":"Filter by exact ticker symbol (uppercased server-side, e.g. AAPL)."},"required":false,"name":"owner_ticker","in":"query"},{"schema":{"type":"string","description":"Filter by exact LEI (uppercased server-side)."},"required":false,"name":"owner_lei","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, returns total_count in the pagination object (exact up to 10,000, then total_count_approximate=true)."},"required":false,"name":"include_total","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["status_stage","office_code","jurisdiction_code","nice_classes","filing_year","mark_feature_type","mark_legal_category","filing_route","right_kind","scope_kind","firm_id","attorney_id","owner_country","owner_id","entity_id","owner_count","entity_count"]},"maxItems":100,"description":"Faceted bucket counts (TMview \"Statistics view\"). Comma-separated field names. Buckets respect every filter by default; see `aggregation_mode`. Values: status_stage, office_code, jurisdiction_code, nice_classes, filing_year, mark_feature_type, mark_legal_category, filing_route, right_kind, scope_kind, firm_id, attorney_id, owner_country, owner_id, entity_id, owner_count, entity_count. Bucket lists are top-N (owner_id, attorney_id, firm_id, entity_id: top 50). owner_count and entity_count return { value }: distinct owner records (per office) and distinct linked companies across offices (owners not yet linked to an entity are not counted) in the result set, close to exact up to 40,000."},"required":false,"name":"aggregations","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["filtered","exclude_own_filter"],"description":"How aggregation counts relate to filters. `filtered` (default): every bucket counts the same filtered set as the results, so buckets add up to `total_count` for single-valued fields. `exclude_own_filter`: each aggregation applies every filter except its own (the `office_code` buckets ignore `offices`, the `nice_classes` buckets ignore `nice_classes`, …), for drill-down sidebars that show the alternatives."},"required":false,"name":"aggregation_mode","in":"query"},{"schema":{"type":["boolean","null"],"description":"When true, return only aggregation counts (size:0) — no result documents."},"required":false,"name":"aggregations_only","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, includes highlight snippets for a ranked q."},"required":false,"name":"highlights","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, includes timing breakdown."},"required":false,"name":"include_timing","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponseV2"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Entity too large: the `?entity_group=` GLEIF family-graph walk exceeded its bound (`error.reason` family_graph_too_large; carries `related_entity_limit`/`depth_limit`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_page","action":"search","status":"available"}}},"/v1/trademarks/{id}/events":{"get":{"operationId":"listTrademarkEvents","tags":["Trademarks"],"description":"Paginated prosecution event timeline for THIS mark, reverse chronological (maps to the trademark_event table): filings, publications, registrations, status changes. This is the office-reported history of a single trademark — not the org-level `/v1/events` activity feed.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Trademark ID (tm_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by event type (comma-separated, case-insensitive): filing, examination_start, office_action, response_filed, approval, publication, opposition_filed, opposition_decided, registration, renewal, cancellation_filed, cancellation_decided, assignment, name_change, address_change, licence_recorded, limitation, correction, appeal_filed, appeal_decided, ceasing_of_effect, central_attack_notification, partial_transfer, partial_cancellation, suspension, extension_requested, extension_granted, payment_received, representative_changed, recordal_received, recordal_registered, amendment_received, revoked, litigation, other. Any other value returns 400."},"required":false,"name":"event_type","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["right","class","designation","proceeding","other"],"description":"Filter by event scope (right, class, designation, proceeding, other)"},"required":false,"name":"event_scope","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Event date >= (YYYY-MM-DD)"},"required":false,"name":"event_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Event date < (YYYY-MM-DD)"},"required":false,"name":"event_date_lt","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Trademark prosecution events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrademarkEventsResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Trademark not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/trademarks/{id}/proceedings":{"get":{"operationId":"listTrademarkProceedings","tags":["Trademarks"],"description":"Proceedings involving this mark, on either side: `trademark_role` is `contested` when the proceeding targets this mark and `asserted` when this mark was pleaded by the opposer or petitioner. Each item includes a parties[] array. Paginated, reverse chronological by filed_date.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Trademark ID (tm_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["contested","asserted"],"description":"Only proceedings where this mark is the `contested` (filed against it) or `asserted` (pleaded by the opposer / petitioner)."},"required":false,"name":"trademark_role","in":"query"},{"schema":{"type":"string","enum":["opposition","cancellation","revocation","invalidity","appeal","non_use_removal","court_action","other"],"description":"Filter by type (opposition, cancellation, revocation, invalidity, appeal, non_use_removal, court_action, other)"},"required":false,"name":"proceeding_type","in":"query"},{"schema":{"type":"string","enum":["pending","decided_granted","decided_rejected","withdrawn","settled","suspended","partial","other"],"description":"Filter by status (pending, decided_granted, decided_rejected, withdrawn, settled, suspended, partial, other)"},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of proceedings with parties","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrademarkProceedingsResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Trademark not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/trademarks/{id}/assignments":{"get":{"operationId":"listTrademarkAssignments","tags":["Trademarks"],"description":"Recorded assignment chain of title for this mark. Each item includes parties[] and properties[]. Paginated, reverse chronological by recorded_date.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Trademark ID (tm_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["assignment","security_interest","release","merger","name_change","license","partial_assignment","correction","entity_conversion","other"],"description":"Filter by conveyance type (assignment, security_interest, release, merger, name_change, license, partial_assignment, correction, entity_conversion, other)"},"required":false,"name":"conveyance_type","in":"query"},{"schema":{"type":"string","enum":["assignment","security_interest","release","merger","name_change","license","partial_assignment","correction","entity_conversion","other"],"description":"Alias for conveyance_type"},"required":false,"name":"type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of assignments with parties and properties","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrademarkAssignmentsResponse"}}}},"400":{"description":"Invalid ID or query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Trademark not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/trademarks/{id}/documents":{"get":{"operationId":"listTrademarkDocuments","tags":["Trademarks"],"description":"Office documents for this mark, such as office actions, certificates, filed forms, and correspondence. USPTO marks are lazily metadata-fetched on first request when no document sync state exists.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Trademark ID (tm_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["office_action","certificate","correspondence","filed_form","other"]},"maxItems":100,"description":"Filter by document kind(s): office_action, certificate, correspondence, filed_form, other"},"required":false,"name":"document_kind","in":"query","style":"form","explode":false},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Official document date >= (YYYY-MM-DD)"},"required":false,"name":"official_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Official document date < (YYYY-MM-DD)"},"required":false,"name":"official_date_lt","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Trademark office documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrademarkDocumentsResponse"}}}},"400":{"description":"Invalid ID or query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Trademark not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/trademarks/{id}/citations":{"get":{"operationId":"listTrademarkCitations","tags":["Trademarks"],"description":"Examiner refusal citations issued AGAINST this mark's application — the prior marks an office cited as a bar to registration. Coverage today is USPTO §2(d) refusals; see `capabilities.citations` on `GET /v1/offices`. Paginated, ordered by `action_date` descending (undated actions last) with `id` as the final tiebreaker. Fixed order — no `sort` parameter.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Trademark ID (tm_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["citation_issued","maintained","withdrawn","abandoned_after","published"]},"maxItems":100,"description":"Filter by disposition (citation_issued, maintained, withdrawn, abandoned_after, published). Comma-separated."},"required":false,"name":"disposition","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["nonfinal","final"]},"maxItems":100,"description":"Filter by office-action stage (nonfinal, final). Comma-separated."},"required":false,"name":"action_stage","in":"query","style":"form","explode":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from a previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Citations against this mark","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationListResponse"}}}},"400":{"description":"Invalid ID, query, or cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Trademark not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/trademarks/{id}/cited-by":{"get":{"operationId":"listTrademarkCitedBy","tags":["Trademarks"],"description":"Applications this mark was cited AGAINST — the refusals where this mark is the prior right. Includes citations matched by reference only (application/registration number), which carry `cited_trademark: null`. Paginated, ordered by `action_date` descending (undated actions last) with `id` as the final tiebreaker. Fixed order — no `sort` parameter.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Trademark ID (tm_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["citation_issued","maintained","withdrawn","abandoned_after","published"]},"maxItems":100,"description":"Filter by disposition (citation_issued, maintained, withdrawn, abandoned_after, published). Comma-separated."},"required":false,"name":"disposition","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["nonfinal","final"]},"maxItems":100,"description":"Filter by office-action stage (nonfinal, final). Comma-separated."},"required":false,"name":"action_stage","in":"query","style":"form","explode":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from a previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Citations naming this mark as the prior right","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationListResponse"}}}},"400":{"description":"Invalid ID, query, or cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Trademark not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/owners/{id}/analytics":{"get":{"operationId":"retrieveOwnerAnalytics","tags":["Analytics"],"description":"Retrieve a composed analytics report for a owner.\n\nCredits: 50 per request.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Analytics report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsReportResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Entity merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":50,"unit":"per_request","action":"analytics","status":"available"}}},"/v1/attorneys/{id}/analytics":{"get":{"operationId":"retrieveAttorneyAnalytics","tags":["Analytics"],"description":"Retrieve a composed analytics report for a attorney.\n\nCredits: 50 per request.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Analytics report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsReportResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Entity merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":50,"unit":"per_request","action":"analytics","status":"available"}}},"/v1/firms/{id}/analytics":{"get":{"operationId":"retrieveFirmAnalytics","tags":["Analytics"],"description":"Retrieve a composed analytics report for a firm.\n\nCredits: 50 per request.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Analytics report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsReportResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Entity merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":50,"unit":"per_request","action":"analytics","status":"available"}}},"/v1/entities/{id}/analytics":{"get":{"operationId":"retrieveEntityAnalytics","tags":["Analytics"],"description":"Retrieve a composed analytics report for an entity, aggregating the portfolio across all resolved member owners.\n\nCredits: 100 per request.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Analytics report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsReportResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Entity merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Entity too large. `error.reason` discriminates: `member_owners_too_large` (the entity resolved to more member owners than the cap; carries `member_count`/`member_count_limit`) or `family_graph_too_large` (the family-graph walk exceeded its bound; carries `related_entity_limit`/`depth_limit`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":100,"unit":"per_request","action":"market_analytics","status":"available"}}},"/v1/analytics/offices/{code}":{"get":{"operationId":"retrieveOfficeAnalytics","tags":["Analytics"],"parameters":[{"schema":{"type":"string","description":"Office code — the WIPO ST.3 code, any case (e.g. US, EM, WO). Legacy internal codes (uspto, euipo, ...) and the EU alias are accepted permanently.","example":"US"},"required":true,"name":"code","in":"path"}],"responses":{"200":{"description":"Office analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficeAnalyticsResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":100,"unit":"per_request","action":"market_analytics","status":"available"},"description":"Credits: 100 per request."}},"/v1/analytics/market":{"get":{"operationId":"retrieveMarketAnalytics","tags":["Analytics"],"responses":{"200":{"description":"Market analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketAnalyticsResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":100,"unit":"per_request","action":"market_analytics","status":"available"},"description":"Credits: 100 per request."}},"/v1/analytics/classifications/{class}":{"get":{"operationId":"retrieveClassificationAnalytics","tags":["Analytics"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"class","in":"path"}],"responses":{"200":{"description":"Classification analytics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassificationAnalyticsResponse"}}}},"400":{"description":"Invalid Nice class","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":100,"unit":"per_request","action":"market_analytics","status":"available"},"description":"Credits: 100 per request."}},"/v1/owners/{id}":{"get":{"operationId":"retrieveOwner","tags":["Owners"],"description":"Retrieve a single owner by ID with full detail.\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","description":"Owner ID (own_...)"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Owner detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerResponse"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Entity merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/owners":{"get":{"operationId":"listOwners","tags":["Owners"],"description":"List owners with optional search and filters. Suppressed owners are always excluded.\n\nCredits: 10 per page.","parameters":[{"schema":{"type":"string","maxLength":200,"description":"Fuzzy, typo-tolerant name match. Without `sort`, exact names and larger portfolios rank first; with `ticker`, `lei`, `publicly_traded` or `has_lei`, matches are ordered by trademark count instead."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Filter by the owner's country code, case-insensitive. Office spellings match too: `EU` and `EM` both return owners stored under either, as do `GB` and `UK`. Historical codes such as `DD` or `SU` are accepted. A value that is not a two-letter code returns 400.","example":"US"},"required":false,"name":"country_code","in":"query"},{"schema":{"type":"string","enum":["individual","corporation","partnership","government","association","trust","sole_proprietorship","cooperative","foundation","other"],"description":"Filter by the owner's `legal_form` (the kind of legal person). Valid values: individual, corporation, partnership, government, association, trust, sole_proprietorship, cooperative, foundation, other. Replaces the retired `entity_type` parameter."},"required":false,"name":"legal_form","in":"query"},{"schema":{"type":"string","description":"Owners with this value (case-insensitive) among their tickers: the owner's own SEC tickers or, when it has none and is linked to an entity, the entity's `tickers` (members' SEC tickers and its listing ticker, which can be inherited from a listed ancestor). The `ticker` GET /v1/owners/{id} serves is always one of them. Tickers on GLEIF records do not match.","example":"AAPL"},"required":false,"name":"ticker","in":"query"},{"schema":{"type":"string","description":"Owners with this value (case-insensitive) among their LEIs: the owner's own GLEIF LEIs or, when it has none and is linked to an entity, the entity's LEIs (its own LEI and its members' GLEIF LEIs). The `lei` GET /v1/owners/{id} serves is always one of them.","example":"HWUPKR0MPOU8FGXBT394"},"required":false,"name":"lei","in":"query"},{"schema":{"type":["boolean","null"],"description":"true: owners with an active SEC company with a ticker among their own matches. Reads the owner's own matches only, not its entity's, so it can differ from the `publicly_traded` GET /v1/owners/{id} serves for an owner linked to an entity. false = no confirmed match of its own, NOT confirmed-private."},"required":false,"name":"publicly_traded","in":"query"},{"schema":{"type":["boolean","null"],"description":"true: owners with a GLEIF LEI among their own matches. Reads the owner's own matches only, not its entity's, so it can differ from the `has_lei` GET /v1/owners/{id} serves for an owner linked to an entity. false = no confirmed match of its own."},"required":false,"name":"has_lei","in":"query"},{"schema":{"type":"string","enum":["-trademark_count","trademark_count","-registration_rate","registration_rate","-grant_rate","grant_rate","-latest_filing","latest_filing","-name","name"],"description":"Sort field with optional - prefix for descending. Options: trademark_count, grant_rate, latest_filing, name. `registration_rate` is a deprecated alias of `grant_rate` (same value). Default: -trademark_count"},"required":false,"name":"sort","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, returns total_count in the pagination object."},"required":false,"name":"include_total","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of owners","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Owner search temporarily unavailable (OpenSearch); retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_page","action":"search","status":"available"}}},"/v1/owners/{id}/trademarks":{"get":{"operationId":"listOwnerTrademarks","tags":["Owners"],"description":"List an owner's trademarks with full Appendix A filter support. Returns summary tier.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Owner ID (own_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Search text within this owner's trademarks, ranked through the similarity channels (1-500 characters; one is enough here). One text only: a list of terms is searched with /v1/trademarks."},"required":false,"name":"q","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"Similarity channels for q, comma-separated: identical, fuzzy, embedded, phonetic, lookalike. Default identical,fuzzy,embedded,lookalike; identical is always on. Requires q."},"required":false,"name":"similarity","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the whole mark equals the value (case, accents, punctuation, spacing and trademark notices ignored). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_is","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the value appears as a whole word (or consecutive words) of the mark. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_word","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the mark begins with the value (case, accents, punctuation and spacing folded). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_starts_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the mark ends with the value (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_ends_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the value appears anywhere in the mark (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_contains","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where `*` matches any run, `?` one character, `\\` escapes the next character; everything else is literal. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_pattern","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the whole mark equals the value (case, accents, punctuation, spacing and trademark notices ignored). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_is","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the value appears as a whole word (or consecutive words) of the mark. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_word","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the mark begins with the value (case, accents, punctuation and spacing folded). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_starts_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the mark ends with the value (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_ends_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the value appears anywhere in the mark (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_contains","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where `*` matches any run, `?` one character, `\\` escapes the next character; everything else is literal. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_pattern","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks whose owners are linked to these entities (ent_...). Repeat the key for several ids."},"required":false,"name":"entity_id_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks linked to any entity in these entities' corporate families (ent_...). Repeat the key for several ids."},"required":false,"name":"entity_group_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks held by these owners (own_...). Repeat the key for several ids."},"required":false,"name":"owner_id_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude these trademarks (tm_...); on the grouped view, the family row containing them. Up to 1000. Repeat the key for several ids."},"required":false,"name":"trademark_ids_not","in":"query","style":"form","explode":true},{"schema":{"type":["boolean","null"],"description":"Return 200 with search_meta.complete=false when the engine times out or a shard fails, instead of 503. Default false."},"required":false,"name":"allow_partial","in":"query"},{"schema":{"type":"string","description":"Sort field(s), comma-separated, - prefix for desc. Default: relevance with q, mark text order with a mark_text filter and no q, otherwise -filing_date."},"required":false,"name":"sort","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["pending","active","inactive","unknown","mixed"]},"maxItems":100,"description":"Filter by primary status. Accepts a single value or a comma-separated list (e.g. `active,pending` for live marks). Valid values: pending, active, inactive, unknown, mixed. \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"required":false,"name":"status_primary","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["filed","examining","pending_publication","published","opposition_period","pending_opposition","pending_cancellation","pending_issuance","registered","allowed","abandoned","withdrawn","surrendered","refused","cancelled","invalidated","expired","unknown","mixed"]},"maxItems":100,"description":"Filter by status stage(s). \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"required":false,"name":"status_stage","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["refused","withdrawn","abandoned","cancelled","invalidated","expired","surrendered","revoked","other"]},"maxItems":100,"description":"Filter by status reason(s)"},"required":false,"name":"status_reason","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["opposition_pending","cancellation_pending","invalidation_pending","appeal_pending","court_pending","other_pending"]},"maxItems":100,"description":"Filter by challenge state(s)"},"required":false,"name":"challenge_states","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["word","figurative","combined","three_d","color","sound","motion","hologram","pattern","position","multimedia","scent","taste","texture","other","unknown"]},"maxItems":100,"description":"Filter by mark feature type(s)"},"required":false,"name":"mark_feature_type","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["standard","collective","certification","collective_membership","defensive","guarantee","geographical_indication","other","unknown"]},"maxItems":100,"description":"Filter by mark legal category(s)"},"required":false,"name":"mark_legal_category","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["trademark","trade_name","commercial_notice","geographical_indication","other"],"description":"Filter by right kind. Valid values: trademark, trade_name, commercial_notice, geographical_indication, other."},"required":false,"name":"right_kind","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["direct_national","direct_regional","madrid_ir","madrid_designation","transformation","divisional","unknown"]},"maxItems":100,"description":"Filter by filing route(s)"},"required":false,"name":"filing_route","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["national","regional","international_registration"]},"maxItems":100,"description":"Filter by scope kind(s)"},"required":false,"name":"scope_kind","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Application number (requires office)"},"required":false,"name":"application_number","in":"query"},{"schema":{"type":"string","description":"Registration number (requires office)"},"required":false,"name":"registration_number","in":"query"},{"schema":{"type":"string","description":"International registration number"},"required":false,"name":"ir_number","in":"query"},{"schema":{"type":"string","description":"Office code (required with application_number or registration_number)"},"required":false,"name":"office","in":"query"},{"schema":{"type":"string","description":"Madrid origin office code"},"required":false,"name":"origin_office_code","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by jurisdiction code(s) (UK is read as GB, WIPO as WO)"},"required":false,"name":"jurisdictions","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["protection","direct"],"description":"How jurisdictions filters match: protection (default - includes regional rights whose membership covers the requested territory, e.g. a EUTM for jurisdictions=FR) or direct (literal territory legs only)."},"required":false,"name":"territory_match","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by office code(s)"},"required":false,"name":"offices","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Filter by owner country code. Two-letter country code, case-insensitive. Office spellings match too: `EU` and `EM` both match records stored under either, as do `GB` and `UK` (`WIPO` is read as `WO`). Historical codes such as `DD` or `SU` are accepted; an empty value is no filter; a value that is not a two-letter code returns 400 `unknown_country_code`."},"required":false,"name":"owner_country","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"integer"},"maxItems":100,"description":"Filter by Nice class number(s)"},"required":false,"name":"nice_classes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by Vienna code(s)"},"required":false,"name":"vienna_codes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by U.S. design search code(s)"},"required":false,"name":"us_design_codes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Z]{2}:[A-Z0-9]+$"},"maxItems":100,"description":"Filter by namespaced filing basis code(s), e.g. US:1A"},"required":false,"name":"filing_basis","in":"query","style":"form","explode":false},{"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Filter by the office register (`register.type`), e.g. principal or supplemental (US) or the CIPO register category (CA). Case-insensitive."},"required":false,"name":"register_type","in":"query"},{"schema":{"type":"string","enum":["open","not_started","closed","unknown"],"description":"Filter by derived opposition window status: open, not_started, closed, or unknown."},"required":false,"name":"opposition_status","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Opposition window closes on or after this date (YYYY-MM-DD)."},"required":false,"name":"opposition_closes_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Opposition window closes on or before this date (YYYY-MM-DD)."},"required":false,"name":"opposition_closes_lte","in":"query"},{"schema":{"type":"string","enum":["claimed","none","unknown"],"description":"Filter by seniority claim state: claimed, none, or unknown."},"required":false,"name":"seniority_claims","in":"query"},{"schema":{"type":"string","description":"Filter by goods/services text"},"required":false,"name":"goods_services_text","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date >= (YYYY-MM-DD)"},"required":false,"name":"filing_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date > (YYYY-MM-DD)"},"required":false,"name":"filing_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date <= (YYYY-MM-DD)"},"required":false,"name":"filing_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date < (YYYY-MM-DD)"},"required":false,"name":"filing_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date >= (YYYY-MM-DD)"},"required":false,"name":"registration_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date > (YYYY-MM-DD)"},"required":false,"name":"registration_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date <= (YYYY-MM-DD)"},"required":false,"name":"registration_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date < (YYYY-MM-DD)"},"required":false,"name":"registration_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date >= (YYYY-MM-DD)"},"required":false,"name":"expiry_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date > (YYYY-MM-DD)"},"required":false,"name":"expiry_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date <= (YYYY-MM-DD)"},"required":false,"name":"expiry_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date < (YYYY-MM-DD)"},"required":false,"name":"expiry_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date >= (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date > (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date <= (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date < (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date >= (YYYY-MM-DD)"},"required":false,"name":"publication_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date > (YYYY-MM-DD)"},"required":false,"name":"publication_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date <= (YYYY-MM-DD)"},"required":false,"name":"publication_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date < (YYYY-MM-DD)"},"required":false,"name":"publication_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date on or after (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date after (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date on or before (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date before (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date >= (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date > (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date <= (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date < (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date >= (YYYY-MM-DD)"},"required":false,"name":"priority_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date > (YYYY-MM-DD)"},"required":false,"name":"priority_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date <= (YYYY-MM-DD)"},"required":false,"name":"priority_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date < (YYYY-MM-DD)"},"required":false,"name":"priority_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date >= (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date > (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date <= (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date < (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date >= (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date > (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date <= (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date < (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date >= (YYYY-MM-DD)"},"required":false,"name":"termination_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date > (YYYY-MM-DD)"},"required":false,"name":"termination_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date <= (YYYY-MM-DD)"},"required":false,"name":"termination_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date < (YYYY-MM-DD)"},"required":false,"name":"termination_date_lt","in":"query"},{"schema":{"type":"string","description":"Updated at >= (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_gte","in":"query"},{"schema":{"type":"string","description":"Updated at > (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_gt","in":"query"},{"schema":{"type":"string","description":"Updated at <= (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_lte","in":"query"},{"schema":{"type":"string","description":"Updated at < (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_lt","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Filter by owner name (fuzzy)"},"required":false,"name":"owner_name","in":"query"},{"schema":{"type":"string","description":"Filter by attorney ID (att_...)"},"required":false,"name":"attorney_id","in":"query"},{"schema":{"type":"string","description":"Filter by firm ID (firm_...)"},"required":false,"name":"firm_id","in":"query"},{"schema":{"type":"string","description":"Filter by attorney/firm name (fuzzy)"},"required":false,"name":"attorney_firm_name","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by media presence"},"required":false,"name":"has_media","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by proceedings presence"},"required":false,"name":"has_proceedings","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter Madrid marks"},"required":false,"name":"is_madrid","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter retracted marks"},"required":false,"name":"is_retracted","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter series marks"},"required":false,"name":"is_series_mark","in":"query"},{"schema":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation. Default grouped → one row per mark/IR. Use expanded for one row per Madrid designation."},"required":false,"name":"international_registrations","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["full_goods_services","match_details"]},"maxItems":100,"description":"Comma-separated optional row projections. `full_goods_services` returns full classifications[].goods_services_text. `match_details` adds match.details (the matched lanes and the ranking factors applied) to each hit."},"required":false,"name":"include","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Sparse top-level field projection. id and object are always retained. Fields you do not request are omitted, although the response schema lists every field."},"required":false,"name":"fields","in":"query","style":"form","explode":false},{"schema":{"type":["boolean","null"],"description":"Filter by public trading status. A false/absent value means no confirmed match, NOT confirmed private — owner→company matching covers ~6% of marks."},"required":false,"name":"owner_publicly_traded","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by LEI presence. A false/absent value means no confirmed match — owner→company matching covers ~6% of marks."},"required":false,"name":"owner_has_lei","in":"query"},{"schema":{"type":"string","description":"Filter by exact ticker symbol (uppercased server-side)."},"required":false,"name":"owner_ticker","in":"query"},{"schema":{"type":"string","description":"Filter by exact LEI (uppercased server-side)."},"required":false,"name":"owner_lei","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, returns total_count in the pagination object (exact up to 10,000, then total_count_approximate=true)."},"required":false,"name":"include_total","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, includes highlight snippets for a ranked q."},"required":false,"name":"highlights","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, includes timing breakdown."},"required":false,"name":"include_timing","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Owner's trademarks (summary tier)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerTrademarksV1Response"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Owner merged (entity_merged names the successor)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/owners/{id}/related":{"get":{"operationId":"listOwnerRelated","tags":["Owners"],"description":"List related owners via the GLEIF corporate hierarchy (parent/child relationships) of the `lei` GET /v1/owners/{id} shows: the owner's own first GLEIF LEI, else its entity's.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Owner ID (own_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["parent","child"],"description":"Filter by relationship direction: parent or child. Omit to return both."},"required":false,"name":"direction","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Related owners via corporate hierarchy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnerRelatedResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Owner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Owner merged (entity_merged names the successor)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/attorneys/{id}":{"get":{"operationId":"retrieveAttorney","tags":["Attorneys"],"description":"Retrieve a single attorney by ID with full detail.\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","description":"Attorney ID (att_...)"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Attorney detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttorneyResponse"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Entity merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/attorneys":{"get":{"operationId":"listAttorneys","tags":["Attorneys"],"description":"List attorneys with optional search and filters.\n\nCredits: 10 per page.","parameters":[{"schema":{"type":"string","maxLength":200,"description":"Fuzzy, typo-tolerant attorney name search. Without `sort`, exact names and larger portfolios rank first. Once the attorney search index has been rebuilt it also matches the names of the firms on the attorney's filings."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Filter by firm ID (firm_...): attorneys with at least one current filing that names the firm."},"required":false,"name":"firm_id","in":"query"},{"schema":{"type":"string","description":"Filter by country code. Two-letter country code, case-insensitive. Office spellings match too: `EU` and `EM` both match records stored under either, as do `GB` and `UK` (`WIPO` is read as `WO`). Historical codes such as `DD` or `SU` are accepted; an empty value is no filter; a value that is not a two-letter code returns 400 `unknown_country_code`."},"required":false,"name":"country_code","in":"query"},{"schema":{"type":"string","enum":["-trademark_count","trademark_count","-registration_rate","registration_rate","-grant_rate","grant_rate","-avg_prosecution_days","avg_prosecution_days","-latest_filing","latest_filing","-name","name"],"description":"Sort field with optional - prefix for descending. Options: trademark_count, grant_rate, avg_prosecution_days, latest_filing, name. `registration_rate` is a deprecated alias of `grant_rate` (same value). Default: -trademark_count"},"required":false,"name":"sort","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, returns total_count in the pagination object."},"required":false,"name":"include_total","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of attorneys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttorneyListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Attorney search temporarily unavailable (OpenSearch); retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_page","action":"search","status":"available"}}},"/v1/attorneys/{id}/trademarks":{"get":{"operationId":"listAttorneyTrademarks","tags":["Attorneys"],"description":"List an attorney's trademarks with full Appendix A filter support. Returns summary tier.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Attorney ID (att_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Search text within this attorney's trademarks, ranked through the similarity channels (1-500 characters; one is enough here). One text only: a list of terms is searched with /v1/trademarks."},"required":false,"name":"q","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"Similarity channels for q, comma-separated: identical, fuzzy, embedded, phonetic, lookalike. Default identical,fuzzy,embedded,lookalike; identical is always on. Requires q."},"required":false,"name":"similarity","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the whole mark equals the value (case, accents, punctuation, spacing and trademark notices ignored). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_is","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the value appears as a whole word (or consecutive words) of the mark. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_word","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the mark begins with the value (case, accents, punctuation and spacing folded). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_starts_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the mark ends with the value (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_ends_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the value appears anywhere in the mark (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_contains","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where `*` matches any run, `?` one character, `\\` escapes the next character; everything else is literal. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_pattern","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the whole mark equals the value (case, accents, punctuation, spacing and trademark notices ignored). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_is","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the value appears as a whole word (or consecutive words) of the mark. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_word","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the mark begins with the value (case, accents, punctuation and spacing folded). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_starts_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the mark ends with the value (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_ends_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the value appears anywhere in the mark (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_contains","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where `*` matches any run, `?` one character, `\\` escapes the next character; everything else is literal. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_pattern","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks whose owners are linked to these entities (ent_...). Repeat the key for several ids."},"required":false,"name":"entity_id_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks linked to any entity in these entities' corporate families (ent_...). Repeat the key for several ids."},"required":false,"name":"entity_group_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks held by these owners (own_...). Repeat the key for several ids."},"required":false,"name":"owner_id_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude these trademarks (tm_...); on the grouped view, the family row containing them. Up to 1000. Repeat the key for several ids."},"required":false,"name":"trademark_ids_not","in":"query","style":"form","explode":true},{"schema":{"type":["boolean","null"],"description":"Return 200 with search_meta.complete=false when the engine times out or a shard fails, instead of 503. Default false."},"required":false,"name":"allow_partial","in":"query"},{"schema":{"type":"string","description":"Sort field(s), comma-separated, - prefix for desc. Default: relevance with q, mark text order with a mark_text filter and no q, otherwise -filing_date."},"required":false,"name":"sort","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["pending","active","inactive","unknown","mixed"]},"maxItems":100,"description":"Filter by primary status. Accepts a single value or a comma-separated list (e.g. `active,pending` for live marks). Valid values: pending, active, inactive, unknown, mixed. \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"required":false,"name":"status_primary","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["filed","examining","pending_publication","published","opposition_period","pending_opposition","pending_cancellation","pending_issuance","registered","allowed","abandoned","withdrawn","surrendered","refused","cancelled","invalidated","expired","unknown","mixed"]},"maxItems":100,"description":"Filter by status stage(s). \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"required":false,"name":"status_stage","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["refused","withdrawn","abandoned","cancelled","invalidated","expired","surrendered","revoked","other"]},"maxItems":100,"description":"Filter by status reason(s)"},"required":false,"name":"status_reason","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["opposition_pending","cancellation_pending","invalidation_pending","appeal_pending","court_pending","other_pending"]},"maxItems":100,"description":"Filter by challenge state(s)"},"required":false,"name":"challenge_states","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["word","figurative","combined","three_d","color","sound","motion","hologram","pattern","position","multimedia","scent","taste","texture","other","unknown"]},"maxItems":100,"description":"Filter by mark feature type(s)"},"required":false,"name":"mark_feature_type","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["standard","collective","certification","collective_membership","defensive","guarantee","geographical_indication","other","unknown"]},"maxItems":100,"description":"Filter by mark legal category(s)"},"required":false,"name":"mark_legal_category","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["trademark","trade_name","commercial_notice","geographical_indication","other"],"description":"Filter by right kind. Valid values: trademark, trade_name, commercial_notice, geographical_indication, other."},"required":false,"name":"right_kind","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["direct_national","direct_regional","madrid_ir","madrid_designation","transformation","divisional","unknown"]},"maxItems":100,"description":"Filter by filing route(s)"},"required":false,"name":"filing_route","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["national","regional","international_registration"]},"maxItems":100,"description":"Filter by scope kind(s)"},"required":false,"name":"scope_kind","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Application number (requires office)"},"required":false,"name":"application_number","in":"query"},{"schema":{"type":"string","description":"Registration number (requires office)"},"required":false,"name":"registration_number","in":"query"},{"schema":{"type":"string","description":"International registration number"},"required":false,"name":"ir_number","in":"query"},{"schema":{"type":"string","description":"Office code (required with application_number or registration_number)"},"required":false,"name":"office","in":"query"},{"schema":{"type":"string","description":"Madrid origin office code"},"required":false,"name":"origin_office_code","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by jurisdiction code(s) (UK is read as GB, WIPO as WO)"},"required":false,"name":"jurisdictions","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["protection","direct"],"description":"How jurisdictions filters match: protection (default - includes regional rights whose membership covers the requested territory, e.g. a EUTM for jurisdictions=FR) or direct (literal territory legs only)."},"required":false,"name":"territory_match","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by office code(s)"},"required":false,"name":"offices","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Filter by owner country code. Two-letter country code, case-insensitive. Office spellings match too: `EU` and `EM` both match records stored under either, as do `GB` and `UK` (`WIPO` is read as `WO`). Historical codes such as `DD` or `SU` are accepted; an empty value is no filter; a value that is not a two-letter code returns 400 `unknown_country_code`."},"required":false,"name":"owner_country","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"integer"},"maxItems":100,"description":"Filter by Nice class number(s)"},"required":false,"name":"nice_classes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by Vienna code(s)"},"required":false,"name":"vienna_codes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by U.S. design search code(s)"},"required":false,"name":"us_design_codes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Z]{2}:[A-Z0-9]+$"},"maxItems":100,"description":"Filter by namespaced filing basis code(s), e.g. US:1A"},"required":false,"name":"filing_basis","in":"query","style":"form","explode":false},{"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Filter by the office register (`register.type`), e.g. principal or supplemental (US) or the CIPO register category (CA). Case-insensitive."},"required":false,"name":"register_type","in":"query"},{"schema":{"type":"string","enum":["open","not_started","closed","unknown"],"description":"Filter by derived opposition window status: open, not_started, closed, or unknown."},"required":false,"name":"opposition_status","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Opposition window closes on or after this date (YYYY-MM-DD)."},"required":false,"name":"opposition_closes_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Opposition window closes on or before this date (YYYY-MM-DD)."},"required":false,"name":"opposition_closes_lte","in":"query"},{"schema":{"type":"string","enum":["claimed","none","unknown"],"description":"Filter by seniority claim state: claimed, none, or unknown."},"required":false,"name":"seniority_claims","in":"query"},{"schema":{"type":"string","description":"Filter by goods/services text"},"required":false,"name":"goods_services_text","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date >= (YYYY-MM-DD)"},"required":false,"name":"filing_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date > (YYYY-MM-DD)"},"required":false,"name":"filing_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date <= (YYYY-MM-DD)"},"required":false,"name":"filing_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date < (YYYY-MM-DD)"},"required":false,"name":"filing_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date >= (YYYY-MM-DD)"},"required":false,"name":"registration_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date > (YYYY-MM-DD)"},"required":false,"name":"registration_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date <= (YYYY-MM-DD)"},"required":false,"name":"registration_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date < (YYYY-MM-DD)"},"required":false,"name":"registration_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date >= (YYYY-MM-DD)"},"required":false,"name":"expiry_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date > (YYYY-MM-DD)"},"required":false,"name":"expiry_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date <= (YYYY-MM-DD)"},"required":false,"name":"expiry_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date < (YYYY-MM-DD)"},"required":false,"name":"expiry_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date >= (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date > (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date <= (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date < (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date >= (YYYY-MM-DD)"},"required":false,"name":"publication_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date > (YYYY-MM-DD)"},"required":false,"name":"publication_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date <= (YYYY-MM-DD)"},"required":false,"name":"publication_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date < (YYYY-MM-DD)"},"required":false,"name":"publication_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date on or after (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date after (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date on or before (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date before (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date >= (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date > (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date <= (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date < (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date >= (YYYY-MM-DD)"},"required":false,"name":"priority_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date > (YYYY-MM-DD)"},"required":false,"name":"priority_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date <= (YYYY-MM-DD)"},"required":false,"name":"priority_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date < (YYYY-MM-DD)"},"required":false,"name":"priority_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date >= (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date > (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date <= (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date < (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date >= (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date > (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date <= (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date < (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date >= (YYYY-MM-DD)"},"required":false,"name":"termination_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date > (YYYY-MM-DD)"},"required":false,"name":"termination_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date <= (YYYY-MM-DD)"},"required":false,"name":"termination_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date < (YYYY-MM-DD)"},"required":false,"name":"termination_date_lt","in":"query"},{"schema":{"type":"string","description":"Updated at >= (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_gte","in":"query"},{"schema":{"type":"string","description":"Updated at > (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_gt","in":"query"},{"schema":{"type":"string","description":"Updated at <= (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_lte","in":"query"},{"schema":{"type":"string","description":"Updated at < (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_lt","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Filter by owner name (fuzzy)"},"required":false,"name":"owner_name","in":"query"},{"schema":{"type":"string","description":"Filter by owner ID (own_...)"},"required":false,"name":"owner_id","in":"query"},{"schema":{"type":"string","description":"Filter by firm ID (firm_...)"},"required":false,"name":"firm_id","in":"query"},{"schema":{"type":"string","description":"Filter by attorney/firm name (fuzzy)"},"required":false,"name":"attorney_firm_name","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by media presence"},"required":false,"name":"has_media","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by proceedings presence"},"required":false,"name":"has_proceedings","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter Madrid marks"},"required":false,"name":"is_madrid","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter retracted marks"},"required":false,"name":"is_retracted","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter series marks"},"required":false,"name":"is_series_mark","in":"query"},{"schema":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation. Default grouped → one row per mark/IR. Use expanded for one row per Madrid designation."},"required":false,"name":"international_registrations","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["full_goods_services","match_details"]},"maxItems":100,"description":"Comma-separated optional row projections. `full_goods_services` returns full classifications[].goods_services_text. `match_details` adds match.details (the matched lanes and the ranking factors applied) to each hit."},"required":false,"name":"include","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Sparse top-level field projection. id and object are always retained. Fields you do not request are omitted, although the response schema lists every field."},"required":false,"name":"fields","in":"query","style":"form","explode":false},{"schema":{"type":["boolean","null"],"description":"Filter by public trading status. A false/absent value means no confirmed match, NOT confirmed private — owner→company matching covers ~6% of marks."},"required":false,"name":"owner_publicly_traded","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by LEI presence. A false/absent value means no confirmed match — owner→company matching covers ~6% of marks."},"required":false,"name":"owner_has_lei","in":"query"},{"schema":{"type":"string","description":"Filter by exact ticker symbol (uppercased server-side)."},"required":false,"name":"owner_ticker","in":"query"},{"schema":{"type":"string","description":"Filter by exact LEI (uppercased server-side)."},"required":false,"name":"owner_lei","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, returns total_count in the pagination object (exact up to 10,000, then total_count_approximate=true)."},"required":false,"name":"include_total","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, includes highlight snippets for a ranked q."},"required":false,"name":"highlights","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, includes timing breakdown."},"required":false,"name":"include_timing","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Attorney's trademarks (summary tier)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttorneyTrademarksV1Response"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Attorney not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Attorney merged (entity_merged names the successor)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/attorneys/{id}/clients":{"get":{"operationId":"listAttorneyClients","tags":["Attorneys"],"description":"List owners this attorney represents. Derived from trademark_owners and trademark_attorneys intersection.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Attorney ID (att_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Attorney's clients (owners)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttorneyClientsResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Attorney not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Attorney merged (entity_merged names the successor)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/firms/{id}":{"get":{"operationId":"retrieveFirm","tags":["Firms"],"description":"Retrieve a single firm by ID.\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","description":"Firm ID (firm_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Comma-separated relations: attorneys"},"required":false,"name":"include","in":"query","style":"form","explode":false}],"responses":{"200":{"description":"Firm detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmResponse"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Entity merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/firms":{"get":{"operationId":"listFirms","tags":["Firms"],"description":"List firms with optional search and filters.\n\nCredits: 10 per page.","parameters":[{"schema":{"type":"string","description":"Filter by country code. Two-letter country code, case-insensitive. Office spellings match too: `EU` and `EM` both match records stored under either, as do `GB` and `UK` (`WIPO` is read as `WO`). Historical codes such as `DD` or `SU` are accepted; an empty value is no filter; a value that is not a two-letter code returns 400 `unknown_country_code`."},"required":false,"name":"country_code","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Fuzzy, typo-tolerant name match. Without `sort`, exact names and larger portfolios rank first."},"required":false,"name":"q","in":"query"},{"schema":{"type":["integer","null"],"description":"Minimum attorney count"},"required":false,"name":"min_attorneys","in":"query"},{"schema":{"type":["integer","null"],"description":"Minimum trademark count"},"required":false,"name":"min_filings","in":"query"},{"schema":{"type":"string","enum":["-trademark_count","trademark_count","-attorney_count","attorney_count","-registration_rate","registration_rate","-grant_rate","grant_rate","-name","name"],"description":"Sort field with optional - prefix for descending. Options: trademark_count, attorney_count, grant_rate, name. `registration_rate` is a deprecated alias of `grant_rate` (same value). Default: -trademark_count"},"required":false,"name":"sort","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, returns total_count in the pagination object."},"required":false,"name":"include_total","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of firms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Firm search temporarily unavailable (OpenSearch); retry after Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_page","action":"search","status":"available"}}},"/v1/firms/{id}/attorneys":{"get":{"operationId":"listFirmAttorneys","tags":["Firms"],"description":"List the attorneys with at least one current filing that names this firm, with per-firm counts (marks filed naming this firm), sorted by that count.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Firm ID (firm_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Firm's attorneys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmAttorneyListResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Firm not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Firm merged (entity_merged names the successor)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/firms/{id}/trademarks":{"get":{"operationId":"listFirmTrademarks","tags":["Firms"],"description":"List trademarks whose filing names this firm.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Firm ID (firm_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Search text within this firm's trademarks, ranked through the similarity channels (1-500 characters; one is enough here). One text only: a list of terms is searched with /v1/trademarks."},"required":false,"name":"q","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"Similarity channels for q, comma-separated: identical, fuzzy, embedded, phonetic, lookalike. Default identical,fuzzy,embedded,lookalike; identical is always on. Requires q."},"required":false,"name":"similarity","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the whole mark equals the value (case, accents, punctuation, spacing and trademark notices ignored). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_is","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the value appears as a whole word (or consecutive words) of the mark. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_word","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the mark begins with the value (case, accents, punctuation and spacing folded). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_starts_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the mark ends with the value (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_ends_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the value appears anywhere in the mark (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_contains","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where `*` matches any run, `?` one character, `\\` escapes the next character; everything else is literal. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_pattern","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the whole mark equals the value (case, accents, punctuation, spacing and trademark notices ignored). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_is","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the value appears as a whole word (or consecutive words) of the mark. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_word","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the mark begins with the value (case, accents, punctuation and spacing folded). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_starts_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the mark ends with the value (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_ends_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the value appears anywhere in the mark (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_contains","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where `*` matches any run, `?` one character, `\\` escapes the next character; everything else is literal. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_pattern","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks whose owners are linked to these entities (ent_...). Repeat the key for several ids."},"required":false,"name":"entity_id_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks linked to any entity in these entities' corporate families (ent_...). Repeat the key for several ids."},"required":false,"name":"entity_group_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks held by these owners (own_...). Repeat the key for several ids."},"required":false,"name":"owner_id_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude these trademarks (tm_...); on the grouped view, the family row containing them. Up to 1000. Repeat the key for several ids."},"required":false,"name":"trademark_ids_not","in":"query","style":"form","explode":true},{"schema":{"type":["boolean","null"],"description":"Return 200 with search_meta.complete=false when the engine times out or a shard fails, instead of 503. Default false."},"required":false,"name":"allow_partial","in":"query"},{"schema":{"type":"string","description":"Sort field(s), comma-separated, - prefix for desc. Default: relevance with q, mark text order with a mark_text filter and no q, otherwise -filing_date."},"required":false,"name":"sort","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["pending","active","inactive","unknown","mixed"]},"maxItems":100,"description":"Filter by primary status. Accepts a single value or a comma-separated list (e.g. `active,pending` for live marks). Valid values: pending, active, inactive, unknown, mixed. \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"required":false,"name":"status_primary","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["filed","examining","pending_publication","published","opposition_period","pending_opposition","pending_cancellation","pending_issuance","registered","allowed","abandoned","withdrawn","surrendered","refused","cancelled","invalidated","expired","unknown","mixed"]},"maxItems":100,"description":"Filter by status stage(s). \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"required":false,"name":"status_stage","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["refused","withdrawn","abandoned","cancelled","invalidated","expired","surrendered","revoked","other"]},"maxItems":100,"description":"Filter by status reason(s)"},"required":false,"name":"status_reason","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["opposition_pending","cancellation_pending","invalidation_pending","appeal_pending","court_pending","other_pending"]},"maxItems":100,"description":"Filter by challenge state(s)"},"required":false,"name":"challenge_states","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["word","figurative","combined","three_d","color","sound","motion","hologram","pattern","position","multimedia","scent","taste","texture","other","unknown"]},"maxItems":100,"description":"Filter by mark feature type(s)"},"required":false,"name":"mark_feature_type","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["standard","collective","certification","collective_membership","defensive","guarantee","geographical_indication","other","unknown"]},"maxItems":100,"description":"Filter by mark legal category(ies)"},"required":false,"name":"mark_legal_category","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["trademark","trade_name","commercial_notice","geographical_indication","other"],"description":"Filter by right kind. Valid values: trademark, trade_name, commercial_notice, geographical_indication, other."},"required":false,"name":"right_kind","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["direct_national","direct_regional","madrid_ir","madrid_designation","transformation","divisional","unknown"]},"maxItems":100,"description":"Filter by filing route(s)"},"required":false,"name":"filing_route","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["national","regional","international_registration"]},"maxItems":100,"description":"Filter by scope kind(s)"},"required":false,"name":"scope_kind","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Application number (requires office)"},"required":false,"name":"application_number","in":"query"},{"schema":{"type":"string","description":"Registration number (requires office)"},"required":false,"name":"registration_number","in":"query"},{"schema":{"type":"string","description":"International registration number"},"required":false,"name":"ir_number","in":"query"},{"schema":{"type":"string","description":"Office code (required with application_number or registration_number)"},"required":false,"name":"office","in":"query"},{"schema":{"type":"string","description":"Madrid origin office code"},"required":false,"name":"origin_office_code","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by jurisdiction code(s) (UK is read as GB, WIPO as WO)"},"required":false,"name":"jurisdictions","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["protection","direct"],"description":"How jurisdictions filters match: protection (default - includes regional rights whose membership covers the requested territory, e.g. a EUTM for jurisdictions=FR) or direct (literal territory legs only)."},"required":false,"name":"territory_match","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by office code(s)"},"required":false,"name":"offices","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Filter by owner country code. Two-letter country code, case-insensitive. Office spellings match too: `EU` and `EM` both match records stored under either, as do `GB` and `UK` (`WIPO` is read as `WO`). Historical codes such as `DD` or `SU` are accepted; an empty value is no filter; a value that is not a two-letter code returns 400 `unknown_country_code`."},"required":false,"name":"owner_country","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"integer"},"maxItems":100,"description":"Filter by Nice class number(s)"},"required":false,"name":"nice_classes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by Vienna code(s)"},"required":false,"name":"vienna_codes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by U.S. design search code(s)"},"required":false,"name":"us_design_codes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Z]{2}:[A-Z0-9]+$"},"maxItems":100,"description":"Filter by namespaced filing basis code(s), e.g. US:1A"},"required":false,"name":"filing_basis","in":"query","style":"form","explode":false},{"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Filter by the office register (`register.type`), e.g. principal or supplemental (US) or the CIPO register category (CA). Case-insensitive."},"required":false,"name":"register_type","in":"query"},{"schema":{"type":"string","enum":["open","not_started","closed","unknown"],"description":"Filter by derived opposition window status: open, not_started, closed, or unknown."},"required":false,"name":"opposition_status","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Opposition window closes on or after this date (YYYY-MM-DD)."},"required":false,"name":"opposition_closes_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Opposition window closes on or before this date (YYYY-MM-DD)."},"required":false,"name":"opposition_closes_lte","in":"query"},{"schema":{"type":"string","enum":["claimed","none","unknown"],"description":"Filter by seniority claim state: claimed, none, or unknown."},"required":false,"name":"seniority_claims","in":"query"},{"schema":{"type":"string","description":"Filter by goods/services text"},"required":false,"name":"goods_services_text","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date >= (YYYY-MM-DD)"},"required":false,"name":"filing_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date > (YYYY-MM-DD)"},"required":false,"name":"filing_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date <= (YYYY-MM-DD)"},"required":false,"name":"filing_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date < (YYYY-MM-DD)"},"required":false,"name":"filing_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date >= (YYYY-MM-DD)"},"required":false,"name":"registration_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date > (YYYY-MM-DD)"},"required":false,"name":"registration_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date <= (YYYY-MM-DD)"},"required":false,"name":"registration_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date < (YYYY-MM-DD)"},"required":false,"name":"registration_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date >= (YYYY-MM-DD)"},"required":false,"name":"expiry_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date > (YYYY-MM-DD)"},"required":false,"name":"expiry_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date <= (YYYY-MM-DD)"},"required":false,"name":"expiry_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date < (YYYY-MM-DD)"},"required":false,"name":"expiry_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date >= (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date > (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date <= (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date < (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date >= (YYYY-MM-DD)"},"required":false,"name":"publication_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date > (YYYY-MM-DD)"},"required":false,"name":"publication_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date <= (YYYY-MM-DD)"},"required":false,"name":"publication_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date < (YYYY-MM-DD)"},"required":false,"name":"publication_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date on or after (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date after (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date on or before (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date before (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date >= (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date > (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date <= (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date < (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date >= (YYYY-MM-DD)"},"required":false,"name":"priority_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date > (YYYY-MM-DD)"},"required":false,"name":"priority_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date <= (YYYY-MM-DD)"},"required":false,"name":"priority_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date < (YYYY-MM-DD)"},"required":false,"name":"priority_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date >= (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date > (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date <= (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date < (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date >= (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date > (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date <= (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date < (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date >= (YYYY-MM-DD)"},"required":false,"name":"termination_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date > (YYYY-MM-DD)"},"required":false,"name":"termination_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date <= (YYYY-MM-DD)"},"required":false,"name":"termination_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date < (YYYY-MM-DD)"},"required":false,"name":"termination_date_lt","in":"query"},{"schema":{"type":"string","description":"Updated at >= (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_gte","in":"query"},{"schema":{"type":"string","description":"Updated at > (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_gt","in":"query"},{"schema":{"type":"string","description":"Updated at <= (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_lte","in":"query"},{"schema":{"type":"string","description":"Updated at < (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_lt","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Filter by owner name (fuzzy)"},"required":false,"name":"owner_name","in":"query"},{"schema":{"type":"string","description":"Filter by owner ID (own_...)"},"required":false,"name":"owner_id","in":"query"},{"schema":{"type":"string","description":"Filter by attorney ID (att_...)"},"required":false,"name":"attorney_id","in":"query"},{"schema":{"type":"string","description":"Filter by attorney/firm name (fuzzy)"},"required":false,"name":"attorney_firm_name","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by media presence"},"required":false,"name":"has_media","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by proceedings presence"},"required":false,"name":"has_proceedings","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter Madrid marks"},"required":false,"name":"is_madrid","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter retracted marks"},"required":false,"name":"is_retracted","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter series marks"},"required":false,"name":"is_series_mark","in":"query"},{"schema":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation. Default grouped → one row per mark/IR. Use expanded for one row per Madrid designation."},"required":false,"name":"international_registrations","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["full_goods_services","match_details"]},"maxItems":100,"description":"Comma-separated optional row projections. `full_goods_services` returns full classifications[].goods_services_text. `match_details` adds match.details (the matched lanes and the ranking factors applied) to each hit."},"required":false,"name":"include","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Sparse top-level field projection. id and object are always retained. Fields you do not request are omitted, although the response schema lists every field."},"required":false,"name":"fields","in":"query","style":"form","explode":false},{"schema":{"type":["boolean","null"],"description":"Filter by public trading status. A false/absent value means no confirmed match, NOT confirmed private — owner→company matching covers ~6% of marks."},"required":false,"name":"owner_publicly_traded","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by LEI presence. A false/absent value means no confirmed match — owner→company matching covers ~6% of marks."},"required":false,"name":"owner_has_lei","in":"query"},{"schema":{"type":"string","description":"Filter by exact ticker symbol (uppercased server-side)."},"required":false,"name":"owner_ticker","in":"query"},{"schema":{"type":"string","description":"Filter by exact LEI (uppercased server-side)."},"required":false,"name":"owner_lei","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, returns total_count in the pagination object (exact up to 10,000, then total_count_approximate=true)."},"required":false,"name":"include_total","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, includes highlight snippets for a ranked q."},"required":false,"name":"highlights","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, includes timing breakdown."},"required":false,"name":"include_timing","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Firm's trademarks (summary tier)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmTrademarksV1Response"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Firm not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Firm merged (entity_merged names the successor)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/entities/{id}":{"get":{"operationId":"retrieveEntity","tags":["Entities"],"description":"Retrieve a single resolved entity by ID, with member owners + per-link evidence embedded. A retired entity (merged into another) returns 410 with the successor's id. An owner's id with the entity prefix (`ent_<owner id>`, the derived singleton ids earlier releases served) is not an entity and returns 404.\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","description":"Entity ID (ent_...)"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Entity detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityResponse"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Entity merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/entities":{"get":{"operationId":"listEntities","tags":["Entities"],"description":"List resolved entities with optional search and filters. q searches the survivorship name and member name variants. An owner not linked to any entity is not listed (see /v1/owners). Served from the search index: when it is unavailable the endpoint returns 503.\n\nCredits: 10 per page.","parameters":[{"schema":{"type":"string","description":"Fuzzy name search across the survivorship name and member name variants."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Filter by survivorship country code. Two-letter country code, case-insensitive. Office spellings match too: `EU` and `EM` both match records stored under either, as do `GB` and `UK` (`WIPO` is read as `WO`). Historical codes such as `DD` or `SU` are accepted; an empty value is no filter; a value that is not a two-letter code returns 400 `unknown_country_code`."},"required":false,"name":"country_code","in":"query"},{"schema":{"type":"string","enum":["individual","corporation","partnership","government","association","trust","sole_proprietorship","cooperative","foundation","other"],"description":"Filter by the entity's `legal_form` (the kind of legal person). Valid values: individual, corporation, partnership, government, association, trust, sole_proprietorship, cooperative, foundation, other. Replaces the retired `entity_type` parameter."},"required":false,"name":"legal_form","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter to publicly-listed entities: either a member owner is matched to an active SEC company with a ticker, OR the entity itself is listed / a subsidiary of a listed company (entities.listing_status). false/absent = no confirmed listing, NOT confirmed-private."},"required":false,"name":"publicly_traded","in":"query"},{"schema":{"type":"string","description":"Exact ticker symbol (uppercased server-side). Matches DIRECT tickers AND inherited/subsidiary tickers (entities.listing_ticker): an entity inherits the ticker of the nearest listed company up its GLEIF direct-parent chain, else of its listed GLEIF ultimate parent. Subsidiaries without a GLEIF-reported parent are not matched. Ultimate-parent inheritance takes effect after the weekly GLEIF refresh. Also covers member-owner SEC company tickers."},"required":false,"name":"ticker","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter to entities with a GLEIF LEI (the entity survivorship LEI or any member owner GLEIF link)."},"required":false,"name":"has_lei","in":"query"},{"schema":{"type":"string","description":"Exact LEI (uppercased server-side). Matches the entity survivorship LEI or any member owner GLEIF LEI."},"required":false,"name":"lei","in":"query"},{"schema":{"type":"string","enum":["-trademark_count","trademark_count","-name","name","-member_count","member_count"],"description":"Sort field with optional - prefix for descending. Options: trademark_count, name, member_count. Default: -trademark_count (or -relevance with q)."},"required":false,"name":"sort","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, returns total_count in the pagination object (exact up to 10,000, then total_count_approximate=true)."},"required":false,"name":"include_total","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of entities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Entity search temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_page","action":"search","status":"available"}}},"/v1/entities/{id}/trademarks":{"get":{"operationId":"listEntityTrademarks","tags":["Entities"],"description":"List an entity's trademarks (summary tier): every mark whose owner is linked to the entity, with full Appendix A filter support. Scoped exactly like GET /v1/trademarks?entity_id= (the same resolved entity ids, no member-owner cap), so both return the same set for the same entity; the difference is that a missing entity is a 404 here and an empty page there. Rate class: search.\n\nCredits: 10 per page.","parameters":[{"schema":{"type":"string","description":"Entity ID (ent_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Search text within this entity's trademarks, ranked through the similarity channels (1-500 characters; one is enough here). One text only: a list of terms is searched with /v1/trademarks."},"required":false,"name":"q","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"Similarity channels for q, comma-separated: identical, fuzzy, embedded, phonetic, lookalike. Default identical,fuzzy,embedded,lookalike; identical is always on. Requires q."},"required":false,"name":"similarity","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the whole mark equals the value (case, accents, punctuation, spacing and trademark notices ignored). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_is","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the value appears as a whole word (or consecutive words) of the mark. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_word","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the mark begins with the value (case, accents, punctuation and spacing folded). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_starts_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the mark ends with the value (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_ends_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where the value appears anywhere in the mark (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_contains","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Marks where `*` matches any run, `?` one character, `\\` escapes the next character; everything else is literal. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_pattern","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the whole mark equals the value (case, accents, punctuation, spacing and trademark notices ignored). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_is","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the value appears as a whole word (or consecutive words) of the mark. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_word","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the mark begins with the value (case, accents, punctuation and spacing folded). Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_starts_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the mark ends with the value (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_ends_with","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where the value appears anywhere in the mark (folded like starts_with); at least 3 characters. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_contains","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks where `*` matches any run, `?` one character, `\\` escapes the next character; everything else is literal. Repeat the key for several values (any one matches). Up to 100 values of 200 characters."},"required":false,"name":"mark_text_not_pattern","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks whose owners are linked to these entities (ent_...). Repeat the key for several ids."},"required":false,"name":"entity_id_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks linked to any entity in these entities' corporate families (ent_...). Repeat the key for several ids."},"required":false,"name":"entity_group_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude marks held by these owners (own_...). Repeat the key for several ids."},"required":false,"name":"owner_id_not","in":"query","style":"form","explode":true},{"schema":{"type":["array","null"],"items":{"type":"string"},"description":"Exclude these trademarks (tm_...); on the grouped view, the family row containing them. Up to 1000. Repeat the key for several ids."},"required":false,"name":"trademark_ids_not","in":"query","style":"form","explode":true},{"schema":{"type":["boolean","null"],"description":"Return 200 with search_meta.complete=false when the engine times out or a shard fails, instead of 503. Default false."},"required":false,"name":"allow_partial","in":"query"},{"schema":{"type":"string","description":"Sort field(s), comma-separated, - prefix for desc. Default: relevance with q, mark text order with a mark_text filter and no q, otherwise -filing_date."},"required":false,"name":"sort","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["pending","active","inactive","unknown","mixed"]},"maxItems":100,"description":"Filter by primary status. Accepts a single value or comma-separated list. Valid values: pending, active, inactive, unknown, mixed. \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"required":false,"name":"status_primary","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["filed","examining","pending_publication","published","opposition_period","pending_opposition","pending_cancellation","pending_issuance","registered","allowed","abandoned","withdrawn","surrendered","refused","cancelled","invalidated","expired","unknown","mixed"]},"maxItems":100,"description":"Filter by status stage(s). \"mixed\" matches grouped IR rows whose designations disagree; it applies to the grouped view only, and a request served one row per record (international_registrations=expanded, or a grouped fallback) that filters on it is a 400."},"required":false,"name":"status_stage","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["refused","withdrawn","abandoned","cancelled","invalidated","expired","surrendered","revoked","other"]},"maxItems":100,"description":"Filter by status reason(s)"},"required":false,"name":"status_reason","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["opposition_pending","cancellation_pending","invalidation_pending","appeal_pending","court_pending","other_pending"]},"maxItems":100,"description":"Filter by challenge state(s)"},"required":false,"name":"challenge_states","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["word","figurative","combined","three_d","color","sound","motion","hologram","pattern","position","multimedia","scent","taste","texture","other","unknown"]},"maxItems":100,"description":"Filter by mark feature type(s)"},"required":false,"name":"mark_feature_type","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["standard","collective","certification","collective_membership","defensive","guarantee","geographical_indication","other","unknown"]},"maxItems":100,"description":"Filter by mark legal category(s)"},"required":false,"name":"mark_legal_category","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["trademark","trade_name","commercial_notice","geographical_indication","other"],"description":"Filter by right kind. Valid values: trademark, trade_name, commercial_notice, geographical_indication, other."},"required":false,"name":"right_kind","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["direct_national","direct_regional","madrid_ir","madrid_designation","transformation","divisional","unknown"]},"maxItems":100,"description":"Filter by filing route(s)"},"required":false,"name":"filing_route","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["national","regional","international_registration"]},"maxItems":100,"description":"Filter by scope kind(s)"},"required":false,"name":"scope_kind","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Application number (requires office)"},"required":false,"name":"application_number","in":"query"},{"schema":{"type":"string","description":"Registration number (requires office)"},"required":false,"name":"registration_number","in":"query"},{"schema":{"type":"string","description":"International registration number"},"required":false,"name":"ir_number","in":"query"},{"schema":{"type":"string","description":"Office code (required with application_number or registration_number)"},"required":false,"name":"office","in":"query"},{"schema":{"type":"string","description":"Madrid origin office code"},"required":false,"name":"origin_office_code","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by jurisdiction code(s) (UK is read as GB, WIPO as WO)"},"required":false,"name":"jurisdictions","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["protection","direct"],"description":"How jurisdictions filters match: protection (default - includes regional rights whose membership covers the requested territory, e.g. a EUTM for jurisdictions=FR) or direct (literal territory legs only)."},"required":false,"name":"territory_match","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by office code(s)"},"required":false,"name":"offices","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Filter by owner country code. Two-letter country code, case-insensitive. Office spellings match too: `EU` and `EM` both match records stored under either, as do `GB` and `UK` (`WIPO` is read as `WO`). Historical codes such as `DD` or `SU` are accepted; an empty value is no filter; a value that is not a two-letter code returns 400 `unknown_country_code`."},"required":false,"name":"owner_country","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"integer"},"maxItems":100,"description":"Filter by Nice class number(s)"},"required":false,"name":"nice_classes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by Vienna code(s)"},"required":false,"name":"vienna_codes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by U.S. design search code(s)"},"required":false,"name":"us_design_codes","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","pattern":"^[A-Z]{2}:[A-Z0-9]+$"},"maxItems":100,"description":"Filter by namespaced filing basis code(s), e.g. US:1A"},"required":false,"name":"filing_basis","in":"query","style":"form","explode":false},{"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Filter by the office register (`register.type`), e.g. principal or supplemental (US) or the CIPO register category (CA). Case-insensitive."},"required":false,"name":"register_type","in":"query"},{"schema":{"type":"string","enum":["open","not_started","closed","unknown"],"description":"Filter by derived opposition window status: open, not_started, closed, or unknown."},"required":false,"name":"opposition_status","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Opposition window closes on or after this date (YYYY-MM-DD)."},"required":false,"name":"opposition_closes_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Opposition window closes on or before this date (YYYY-MM-DD)."},"required":false,"name":"opposition_closes_lte","in":"query"},{"schema":{"type":"string","enum":["claimed","none","unknown"],"description":"Filter by seniority claim state: claimed, none, or unknown."},"required":false,"name":"seniority_claims","in":"query"},{"schema":{"type":"string","description":"Filter by goods/services text"},"required":false,"name":"goods_services_text","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date >= (YYYY-MM-DD)"},"required":false,"name":"filing_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date > (YYYY-MM-DD)"},"required":false,"name":"filing_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date <= (YYYY-MM-DD)"},"required":false,"name":"filing_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filing date < (YYYY-MM-DD)"},"required":false,"name":"filing_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date >= (YYYY-MM-DD)"},"required":false,"name":"registration_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date > (YYYY-MM-DD)"},"required":false,"name":"registration_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date <= (YYYY-MM-DD)"},"required":false,"name":"registration_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Registration date < (YYYY-MM-DD)"},"required":false,"name":"registration_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date >= (YYYY-MM-DD)"},"required":false,"name":"expiry_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date > (YYYY-MM-DD)"},"required":false,"name":"expiry_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date <= (YYYY-MM-DD)"},"required":false,"name":"expiry_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Expiry date < (YYYY-MM-DD)"},"required":false,"name":"expiry_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date >= (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date > (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date <= (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Renewal due date < (YYYY-MM-DD)"},"required":false,"name":"renewal_due_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date >= (YYYY-MM-DD)"},"required":false,"name":"publication_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date > (YYYY-MM-DD)"},"required":false,"name":"publication_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date <= (YYYY-MM-DD)"},"required":false,"name":"publication_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Publication date < (YYYY-MM-DD)"},"required":false,"name":"publication_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date on or after (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date after (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date on or before (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Designation date before (YYYY-MM-DD). Date the designation was made under the Madrid Protocol (international registration date, or the subsequent-designation date). Set on Madrid designation records. Record grain only: the default grouped view falls back to one row per record with an `expanded_fallback` warning, and international_registrations=grouped returns 400."},"required":false,"name":"designation_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date >= (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date > (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date <= (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Status effective date < (YYYY-MM-DD)"},"required":false,"name":"status_effective_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date >= (YYYY-MM-DD)"},"required":false,"name":"priority_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date > (YYYY-MM-DD)"},"required":false,"name":"priority_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date <= (YYYY-MM-DD)"},"required":false,"name":"priority_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Priority date < (YYYY-MM-DD)"},"required":false,"name":"priority_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date >= (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date > (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date <= (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use anywhere date < (YYYY-MM-DD)"},"required":false,"name":"first_use_anywhere_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date >= (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date > (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date <= (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First use in commerce date < (YYYY-MM-DD)"},"required":false,"name":"first_use_in_commerce_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date >= (YYYY-MM-DD)"},"required":false,"name":"termination_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date > (YYYY-MM-DD)"},"required":false,"name":"termination_date_gt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date <= (YYYY-MM-DD)"},"required":false,"name":"termination_date_lte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Termination date < (YYYY-MM-DD)"},"required":false,"name":"termination_date_lt","in":"query"},{"schema":{"type":"string","description":"Updated at >= (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_gte","in":"query"},{"schema":{"type":"string","description":"Updated at > (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_gt","in":"query"},{"schema":{"type":"string","description":"Updated at <= (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_lte","in":"query"},{"schema":{"type":"string","description":"Updated at < (YYYY-MM-DD or ISO 8601)"},"required":false,"name":"updated_at_lt","in":"query"},{"schema":{"type":"string","description":"Filter by owner name (fuzzy)"},"required":false,"name":"owner_name","in":"query"},{"schema":{"type":"string","description":"Filter by attorney ID (att_...)"},"required":false,"name":"attorney_id","in":"query"},{"schema":{"type":"string","description":"Filter by firm ID (firm_...)"},"required":false,"name":"firm_id","in":"query"},{"schema":{"type":"string","description":"Filter by attorney/firm name (fuzzy)"},"required":false,"name":"attorney_firm_name","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by media presence"},"required":false,"name":"has_media","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by proceedings presence"},"required":false,"name":"has_proceedings","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter Madrid marks"},"required":false,"name":"is_madrid","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter retracted marks"},"required":false,"name":"is_retracted","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter series marks"},"required":false,"name":"is_series_mark","in":"query"},{"schema":{"type":"string","enum":["grouped","expanded"],"description":"International registration presentation. Default grouped → one row per mark/IR. Use expanded for one row per Madrid designation."},"required":false,"name":"international_registrations","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["full_goods_services","match_details"]},"maxItems":100,"description":"Comma-separated optional row projections. `full_goods_services` returns full classifications[].goods_services_text. `match_details` adds match.details (the matched lanes and the ranking factors applied) to each hit."},"required":false,"name":"include","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Sparse top-level field projection. id and object are always retained. Fields you do not request are omitted, although the response schema lists every field."},"required":false,"name":"fields","in":"query","style":"form","explode":false},{"schema":{"type":["boolean","null"],"description":"Filter by public trading status."},"required":false,"name":"owner_publicly_traded","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by LEI presence."},"required":false,"name":"owner_has_lei","in":"query"},{"schema":{"type":"string","description":"Filter by exact ticker symbol (uppercased server-side)."},"required":false,"name":"owner_ticker","in":"query"},{"schema":{"type":"string","description":"Filter by exact LEI (uppercased server-side)."},"required":false,"name":"owner_lei","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, expand the trademark set to this entity AND all of its family-tree descendants (via entities.parent_entity_id, a bounded cycle-safe downward walk), then run the same query over the expanded entity set. Default false (this entity only). A family graph larger than the walk bounds returns 422 (family_graph_too_large)."},"required":false,"name":"include_family","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, returns total_count in the pagination object (exact up to 10,000, then total_count_approximate=true)."},"required":false,"name":"include_total","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, includes highlight snippets for a ranked q."},"required":false,"name":"highlights","in":"query"},{"schema":{"type":["boolean","null"],"description":"If true, includes timing breakdown."},"required":false,"name":"include_timing","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Entity's trademarks (summary tier)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityTrademarksV1Response"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Entity merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Family graph too large: `?include_family=true` walked a family-tree larger than the bound (`error.reason` `family_graph_too_large`; carries `related_entity_limit`/`depth_limit`). There is no member-owner cap: an entity of any size lists without `include_family`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_page","action":"search","status":"available"}}},"/v1/entities/{id}/family":{"get":{"operationId":"retrieveEntityFamily","tags":["Entities"],"description":"Retrieve an entity's direct GLEIF corporate family (1 level): parent + direct subsidiaries, sourced from GLEIF Level 2 (IS_DIRECTLY_CONSOLIDATED_BY). Covers LEI-reporting companies only — an absent edge does not imply the absence of a corporate relationship (see coverage_caveat). An entity with no edges returns parent: null, children: [].\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","description":"Entity ID (ent_...)"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Entity family (parent + children)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityFamilyResponse"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Entity merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/proceedings":{"get":{"operationId":"listProceedings","tags":["Proceedings"],"description":"List proceedings across all trademarks. At least one filter is required. Proceedings are served only for offices whose `capabilities.proceedings` on `GET /v1/offices` is `available`; an `office_code` naming any other live office returns 422 `capability_not_available` without running a query or charging credits.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":45,"description":"Filter by Nice class involved in the dispute (1-45)"},"required":false,"description":"Filter by Nice class involved in the dispute (1-45)","name":"contested_class","in":"query"},{"schema":{"type":"string","description":"Filter by trademark ID (tm_...)"},"required":false,"description":"Filter by trademark ID (tm_...)","name":"trademark_id","in":"query"},{"schema":{"type":"string","enum":["opposition","cancellation","revocation","invalidity","appeal","non_use_removal","court_action","other"],"description":"Filter by proceeding type (opposition, cancellation, revocation, invalidity, appeal, non_use_removal, court_action, other). A type that no office with `capabilities.proceedings = \"available\"` records (or that the requested `office_code` does not record) returns an empty page without running a query."},"required":false,"description":"Filter by proceeding type (opposition, cancellation, revocation, invalidity, appeal, non_use_removal, court_action, other). A type that no office with `capabilities.proceedings = \"available\"` records (or that the requested `office_code` does not record) returns an empty page without running a query.","name":"proceeding_type","in":"query"},{"schema":{"type":"string","enum":["pending","decided_granted","decided_rejected","withdrawn","settled","suspended","partial","other"],"description":"Filter by status (pending, decided_granted, decided_rejected, withdrawn, settled, suspended, partial, other)"},"required":false,"description":"Filter by status (pending, decided_granted, decided_rejected, withdrawn, settled, suspended, partial, other)","name":"status","in":"query"},{"schema":{"type":"string","description":"Search party name: a case-insensitive substring of a party name as the office recorded it (`%` and `_` match literally). It matches names only; it does not resolve related companies or subsidiaries. Combined with `party_role`, `party_owner_id` or `party_entity_id`, every party filter must match the same party: `q=Acme&party_role=opponent` returns proceedings where a party named Acme is the opponent."},"required":false,"description":"Search party name: a case-insensitive substring of a party name as the office recorded it (`%` and `_` match literally). It matches names only; it does not resolve related companies or subsidiaries. Combined with `party_role`, `party_owner_id` or `party_entity_id`, every party filter must match the same party: `q=Acme&party_role=opponent` returns proceedings where a party named Acme is the opponent.","name":"q","in":"query"},{"schema":{"type":"string","description":"Filter by party owner ID (own_...): proceedings where a party is linked to this owner. A party is linked only when the marks in the dispute show which owner it is and the names match with the same company suffix. Parties without a link are not returned, for example most Canadian and Australian opponents (they are matched only against the owner of the mark under challenge), a name that matches only without its company suffix, or a recorded name that lists several parties. Use `q` to match by name or for complete coverage."},"required":false,"description":"Filter by party owner ID (own_...): proceedings where a party is linked to this owner. A party is linked only when the marks in the dispute show which owner it is and the names match with the same company suffix. Parties without a link are not returned, for example most Canadian and Australian opponents (they are matched only against the owner of the mark under challenge), a name that matches only without its company suffix, or a recorded name that lists several parties. Use `q` to match by name or for complete coverage.","name":"party_owner_id","in":"query"},{"schema":{"type":"string","description":"Filter by resolved or derived entity ID (ent_...): proceedings where a party is linked to any member owner of the entity. Linking works as for `party_owner_id`, and parties without a link are not returned; use `q` to match by name or for complete coverage. A malformed id returns 400 and an entity with more member owners than the cap returns 422 `entity_too_large`."},"required":false,"description":"Filter by resolved or derived entity ID (ent_...): proceedings where a party is linked to any member owner of the entity. Linking works as for `party_owner_id`, and parties without a link are not returned; use `q` to match by name or for complete coverage. A malformed id returns 400 and an entity with more member owners than the cap returns 422 `entity_too_large`.","name":"party_entity_id","in":"query"},{"schema":{"type":"string","description":"Alias for party_entity_id (ent_...), with the same matching and validation (400 / 422 `entity_too_large`)."},"required":false,"description":"Alias for party_entity_id (ent_...), with the same matching and validation (400 / 422 `entity_too_large`).","name":"entity_id","in":"query"},{"schema":{"type":"string","enum":["opponent","petitioner","respondent","intervener","other"],"description":"Filter by party role. Combined with `q`, the party whose name matches must hold this role. The `party_role` aggregation still counts every role on the matching proceedings."},"required":false,"description":"Filter by party role. Combined with `q`, the party whose name matches must hold this role. The `party_role` aggregation still counts every role on the matching proceedings.","name":"party_role","in":"query"},{"schema":{"type":"string","enum":["contested","asserted"],"description":"Filter by the linked mark's side: `contested` (the opposed / appealed mark) or `asserted` (a mark the opposer or petitioner pleaded). Distinct from `party_role`, which is about the named parties."},"required":false,"description":"Filter by the linked mark's side: `contested` (the opposed / appealed mark) or `asserted` (a mark the opposer or petitioner pleaded). Distinct from `party_role`, which is about the named parties.","name":"trademark_role","in":"query"},{"schema":{"type":"string","description":"Filter by trademark office code. WIPO ST.3 uppercase (e.g. US, EM); legacy acronym slugs (uspto, euipo) and EU are also accepted. A live office whose `capabilities.proceedings` on GET /v1/offices is not `available` returns 422 `capability_not_available`; an unknown or planned office code returns 400."},"required":false,"description":"Filter by trademark office code. WIPO ST.3 uppercase (e.g. US, EM); legacy acronym slugs (uspto, euipo) and EU are also accepted. A live office whose `capabilities.proceedings` on GET /v1/offices is not `available` returns 422 `capability_not_available`; an unknown or planned office code returns 400.","name":"office_code","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filed date >= (YYYY-MM-DD)"},"required":false,"description":"Filed date >= (YYYY-MM-DD)","name":"filed_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Filed date < (YYYY-MM-DD)"},"required":false,"description":"Filed date < (YYYY-MM-DD)","name":"filed_date_lt","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Decision date >= (YYYY-MM-DD)"},"required":false,"description":"Decision date >= (YYYY-MM-DD)","name":"decision_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Decision date < (YYYY-MM-DD)"},"required":false,"description":"Decision date < (YYYY-MM-DD)","name":"decision_date_lt","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["outcome","party_role","nice_class","office_code","filed_year","trademark_role"]},"maxItems":100,"description":"Optional faceted bucket maps (outcome, party_role, nice_class, office_code, filed_year, trademark_role)"},"required":false,"name":"aggregations","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["-filed_date","filed_date","-decided_date","decided_date"],"description":"Sort field with optional - prefix for descending. Default: -filed_date"},"required":false,"description":"Sort field with optional - prefix for descending. Default: -filed_date","name":"sort","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"description":"Pagination cursor from previous response","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of proceedings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProceedingListResponse"}}}},"400":{"description":"Missing filter or invalid params, including an unknown or planned (not live) `office_code`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Two cases, told apart by `error.type`. `capability_not_available`: `office_code` names a live office whose proceedings Signa does not serve (`capabilities.proceedings` on `GET /v1/offices` is not `available`); the error carries `capability`, `capability_state` and `office_code`, no query is run and no credits are charged. `entity_too_large`: `error.reason` is `member_owners_too_large` (`?party_entity_id=`/`?entity_id=` resolved to more member owners than the cap; carries `member_count`/`member_count_limit`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/proceedings/{id}":{"get":{"operationId":"retrieveProceeding","tags":["Proceedings"],"description":"Retrieve a single proceeding by ID, including parent trademark summary. A proceeding on a mark of an office whose `capabilities.proceedings` is not `available` is not served (404).\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","description":"Proceeding ID (prc_...)"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Proceeding detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProceedingResponse"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/citations":{"get":{"operationId":"listCitations","tags":["Citations"],"description":"List examiner refusal citations across all marks — the prior marks an office cited against an application. Coverage today is USPTO §2(d) refusals; check `capabilities.citations` on `GET /v1/offices` for the per-office state. Extracted hourly from office actions; dispositions are refreshed daily. Ordered by `action_date` (undated actions last) with `id` as the final tiebreaker.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by issuing office, comma-separated (e.g. US,EM). WIPO ST.3 uppercase (e.g. US); legacy acronym slugs (uspto) and EU are also accepted. Values are OR-ed: an unknown code contributes no matches rather than erroring, so the list is empty only when NONE of the supplied codes match (`?offices=US,ZZ` still returns the US rows)."},"required":false,"name":"offices","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["citation_issued","maintained","withdrawn","abandoned_after","published"]},"maxItems":100,"description":"Filter by disposition (citation_issued, maintained, withdrawn, abandoned_after, published). Comma-separated."},"required":false,"name":"disposition","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["nonfinal","final"]},"maxItems":100,"description":"Filter by office-action stage (nonfinal, final). Comma-separated."},"required":false,"name":"action_stage","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["2d"]},"maxItems":100,"description":"Filter by refusal ground (2d). Office-local vocabulary."},"required":false,"name":"refusal_type","in":"query","style":"form","explode":false},{"schema":{"type":"string","minLength":1,"description":"Filter by citing application (tm_...). Must not be blank."},"required":false,"name":"trademark_id","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Filter by cited mark (tm_...). Must not be blank. Matches the same rows as `GET /v1/trademarks/{id}/cited-by`, which includes REFERENCE-MATCHED citations: rows whose `cited_trademark` is `null` because the cited mark was never resolved to a link, but whose `cited_ref` is this mark's application or registration number in the same office. So a returned row does not necessarily carry the id you filtered on — do not assert `cited_trademark.id === <filter>`."},"required":false,"name":"cited_trademark_id","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Exact cited reference (digits; punctuation is ignored). Must not be blank. Requires `offices` — an office-less reference lookup is unindexable."},"required":false,"name":"cited_ref","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Office action date >= (YYYY-MM-DD)"},"required":false,"name":"action_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Office action date <= (YYYY-MM-DD)"},"required":false,"name":"action_date_lte","in":"query"},{"schema":{"type":"string","enum":["-action_date","action_date"],"default":"-action_date","description":"Sort field with optional - prefix for descending. Default: -action_date"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from a previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of citations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitationListResponse"}}}},"400":{"description":"Invalid query (bad enum, `cited_ref` without `offices`, malformed or expired cursor)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/assignments":{"get":{"operationId":"listAssignments","tags":["Assignments"],"description":"List recorded trademark assignments. At least one filter is required.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Filter by resolved owner ID (own_...)"},"required":false,"name":"owner_id","in":"query"},{"schema":{"type":"string","description":"Filter by resolved entity ID (ent_...) across its member owners"},"required":false,"name":"entity_id","in":"query"},{"schema":{"type":"string","description":"Filter by trademark ID (tm_...)"},"required":false,"name":"trademark_id","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["assignment","security_interest","release","merger","name_change","license","partial_assignment","correction","entity_conversion","other"]},"maxItems":100,"description":"Filter by conveyance type (assignment, security_interest, release, merger, name_change, license, partial_assignment, correction, entity_conversion, other)"},"required":false,"name":"conveyance_type","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["assignment","security_interest","release","merger","name_change","license","partial_assignment","correction","entity_conversion","other"]},"maxItems":100,"description":"Alias for conveyance_type"},"required":false,"name":"type","in":"query","style":"form","explode":false},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Recorded date >= (YYYY-MM-DD)"},"required":false,"name":"recorded_date_gte","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Recorded date < (YYYY-MM-DD)"},"required":false,"name":"recorded_date_lt","in":"query"},{"schema":{"type":"string","enum":["assignor","assignee"],"description":"Filter by assignment party role"},"required":false,"name":"role","in":"query"},{"schema":{"type":"string","enum":["-recorded_date","recorded_date"],"description":"Sort field with optional - prefix for descending. Default: -recorded_date"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor from previous response"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of assignments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignmentListResponse"}}}},"400":{"description":"Missing filter or invalid params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Entity too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/assignments/{id}":{"get":{"operationId":"retrieveAssignment","tags":["Assignments"],"description":"Retrieve a single recorded trademark assignment.\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","description":"Assignment ID (asg_...)"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Assignment detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignmentResponse"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/deadlines/compute":{"post":{"operationId":"computeDeadlines","tags":["Deadlines"],"description":"Compute maintenance deadlines for one or more trademarks without persisting data. Items may contain a stored trademark `id` (server-resolved maintenance inputs and prosecution event facts) or caller-supplied facts. Unknown IDs return per-item errors. Supply `items[].facts` to also compute prosecution deadlines (office-action responses, statements of use) per fact instance; every computed prosecution date cites the rule, era and sources behind it. Omitting `facts` leaves the item without `prosecution_deadlines` and `support`; every other field, including the rule-identity provenance (`sources`, `as_of`, `computed_at`), is returned either way.\n\nCredits: 10 per item.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeadlineComputeRequest"}}}},"responses":{"200":{"description":"Computed deadline results, one result per input item in request order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeadlineComputeResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Batch too large — too many items, or too many prosecution facts across the batch. Carries `error.item_count` and `error.item_count_limit`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_item","action":"compute","status":"available"}}},"/v1/deadlines":{"get":{"operationId":"listDeadlines","tags":["Deadlines"],"description":"Compute maintenance deadlines on read for exactly one portfolio or trademark. Every request requires trademarks:read; a portfolio_id request additionally requires portfolios:manage. Costs 1 credit per page. Sorted by due_date, trademark_id and rule_id ascending. The cursor pins the computation date, not a snapshot of records.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":["array","null"],"items":{"type":"string","enum":["renewal","declaration_of_use","combined_renewal_and_use","declaration_of_incontestability","restoration","international_renewal","post_registration_oa_response"]},"maxItems":100,"description":"Deadline types"},"required":false,"name":"type","in":"query","style":"form","explode":false},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive due-date cutoff. ISO 8601 calendar date, `YYYY-MM-DD`; any other format is rejected with 400 `validation_error`. Defaults to 720 days after the pinned computation date; schedules use a five-year horizon, and a later `due_before` adds a `horizon_truncated` entry to `warnings`.","example":"2027-06-30"},"required":false,"name":"due_before","in":"query"},{"schema":{"type":"string","enum":["critical","upcoming","routine","in_grace","missed"]},"required":false,"name":"urgency","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque signed seek cursor. Pins as_of and binds the selector and filters; underlying records may change."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"portfolio_id","in":"query"},{"schema":{"type":"string"},"required":false,"name":"trademark_id","in":"query"}],"responses":{"200":{"description":"Computed deadline list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeadlineListResponse"}}}},"400":{"description":"Invalid selector, filters or cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing `trademarks:read`, or missing `portfolios:manage` on a `portfolio_id` request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Trademark or org-owned portfolio not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Portfolio exceeds 5,000 marks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/fees":{"get":{"operationId":"listFees","tags":["Fees"],"description":"List the bounded fee catalog with native currency amounts and verified source snapshots. Optional office and action filters; no pagination.\n\nCredits: 10 per request.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Office code (WO, US, EM, GB). The platform office codes WIPO, USPTO, EUIPO (also EU), and UKIPO (also UK) are accepted as aliases for WO, US, EM, and GB. Other office or country codes return an empty list; a value that is not an office or country code returns 400."},"required":false,"name":"office","in":"query"},{"schema":{"type":"string","enum":["filing","renewal","declaration_of_use","declaration_of_incontestability","statement_of_use","amendment_to_allege_use","sou_extension","opposition","oa_extension","expungement_oa_extension","petition_to_revive","restoration","continuation","restitutio","subsequent_designation","transfer","name_address_change","limitation","licence","division"]},"required":false,"name":"action","in":"query"}],"responses":{"200":{"description":"Complete filtered fee catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeListResponse"}}}},"304":{"description":"Catalog unchanged"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing trademarks:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_request","action":"rules_lookup","status":"available"}}},"/v1/fees/estimate":{"post":{"operationId":"estimateFees","tags":["Fees"],"description":"Estimate official fees for one request in native currency minor units, without persisting data. Billed as one fee estimate per request. No Idempotency-Key required. Unsupported or unverified components are explicit lines; incomplete estimates have a null total and a partial subtotal. No currency conversion.\n\nCredits: 10 per request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeEstimateRequest"}}}},"responses":{"200":{"description":"Fee estimate, including any unsupported components","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeEstimateResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing trademarks:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_request","action":"fees_estimate","status":"available"}}},"/v1/oppositions/compute":{"post":{"operationId":"computeOppositions","tags":["Oppositions"],"description":"Compute opposition windows for one or more publication dates without persisting data.\n\nCredits: 10 per item.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OppositionComputeRequest"}}}},"responses":{"200":{"description":"Computed opposition windows, one result per input item in request order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OppositionComputeResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Batch too large. Carries `error.item_count` and `error.item_count_limit`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":10,"unit":"per_item","action":"compute","status":"available"}}},"/v1/reconcile":{"post":{"operationId":"reconcile","tags":["Reconciliation"],"description":"Compare caller-held trademark fields against the normalized register copy without persisting data. With `verdict_detail: true`, each result additionally carries a three-source per-field verdict (`field_verdicts[]` — your value vs the register vs the rulebook-computed schedule), a `computed` context block and a `lookup` echo. The flag changes neither `fields[]`, `result`, `mismatch_count` nor billing.\n\nCredits: 1 per item.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileRequest"}}}},"responses":{"200":{"description":"Reconciliation results, one result per input item in request order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Batch too large. Carries `error.item_count` and `error.item_count_limit`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_item","action":"reconcile","status":"available"}}},"/v1/screening":{"get":{"operationId":"screenName","tags":["Screening"],"description":"INTERNAL/alpha — requires the `screening:read` scope (granted to internal + design-partner keys only until GA). Screen a candidate name: a fast synchronous text knockout check returning a coarse go/no-go verdict and risk-banded conflicts. Not legal advice. BETA (flag-gated) `resolution_mode` controls the goods/services resolution cascade: `auto` (default) has BIMODAL latency — a sub-ms/ms deterministic + semantic majority and, once the tier-3 LLM lane lands, a ~4s p50 uncached tail; `deterministic` is the budget-safe, sub-ms/SLA mode that never calls the LLM lane; `llm` is not yet implemented (501).","parameters":[{"schema":{"type":"string","description":"Candidate mark text to screen (min 2 non-whitespace chars). Exactly one of q or trademark_id is required."},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","pattern":"^tm_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$","description":"Existing register record to use as the candidate. Exactly one of q or trademark_id is required.","example":"tm_0190f2d5-8e4b-7c1a-a8d3-123456789abc"},"required":false,"name":"trademark_id","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"integer"},"maxItems":100,"description":"Intended Nice class numbers (hard filter, 1-45)."},"required":false,"name":"nice_classes","in":"query","style":"form","explode":false},{"schema":{"type":"string","maxLength":2000,"description":"Free-text description of intended goods/services. Drives per-hit goods-text similarity and, when nice_classes is omitted, Nice-class inference (surfaced as screening.inferred_nice_classes)."},"required":false,"name":"goods_services","in":"query"},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Restrict to these jurisdiction (territory) codes (UK is read as GB, WIPO as WO). Default: all live-coverage jurisdictions."},"required":false,"name":"jurisdictions","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Restrict to these registering office codes (WIPO ST.3, e.g. US, EM; legacy internal codes accepted). Default: all live offices."},"required":false,"name":"offices","in":"query","style":"form","explode":false},{"schema":{"type":"string","enum":["live","all"],"default":"live","description":"live (default) keeps live marks; all includes dead."},"required":false,"name":"include","in":"query"},{"schema":{"type":"string","enum":["strict","standard","broad"],"default":"standard","description":"Band-admission threshold: strict (exact/normalized), standard (+fuzzy_1/phonetic_strong), broad (+fuzzy_2)."},"required":false,"name":"sensitivity","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Page size (1-50, default 20)."},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Screening result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Candidate trademark not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Candidate trademark has no screenable mark text","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"resolution_mode=llm requested but the tier-3 LLM lane is not enabled yet (BETA, cascade-modes flag on).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Search backend unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/compare":{"post":{"operationId":"compareTrademarks","tags":["Compare"],"description":"INTERNAL/alpha — requires the `screening:read` scope (granted to internal + design-partner keys only until GA). Compare one candidate against 1–10 conflicts. Not legal advice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareRequest"}}}},"responses":{"200":{"description":"Request-ordered pair comparison results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Candidate trademark not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`insufficient_use_profile`, `batch_too_large`, or `not_screenable` when the candidate trademark has no screenable mark text.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Search backend unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}]}},"/v1/screening/listings":{"post":{"operationId":"checkListing","tags":["Screening"],"description":"INTERNAL/alpha — requires the `screening:read` scope (internal + design-partner keys only until GA). Screen a whole LISTING: extract candidate marks from commerce text (title/brand/description/keywords), fan them out through the screening core, and return a listing-level verdict with per-candidate conflicts. Deterministic, synchronous, no LLM at request time. Billed flat per listing regardless of internal fan-out. Not legal advice.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingCheckBody"}}}},"responses":{"200":{"description":"Listing check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingCheckResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Search backend unavailable / internal deadline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/screening/listings/batch":{"post":{"operationId":"submitListingBatch","tags":["Screening"],"description":"INTERNAL/alpha — requires the `screening:read` scope. Submit 1–100 listing-check requests for ASYNCHRONOUS screening with bounded concurrency. Each item is the exact POST /v1/screening/listings body; per-item results are identical to the sync endpoint response modulo request_id. Returns 202 with a job id — poll GET /v1/screening/listings/batch/{id}. Billed per listing. Requires an Idempotency-Key (a retry replays the same 202 + job id; an idempotent replay omits the Location header — use status_url in the body). Not legal advice.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningBatchBody"}}}},"responses":{"202":{"description":"Batch accepted — poll the job for results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningBatchSubmit"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body exceeds the global size cap (~256 KiB) — submit fewer/smaller listings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or quota exceeded (the batch reserves 25 × item_count units up front).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Job store unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}]}},"/v1/screening/listings/batch/{id}":{"get":{"operationId":"getListingBatch","tags":["Screening"],"description":"INTERNAL/alpha — requires the `screening:read` scope. Poll a listing-batch job. Returns status (queued/running/completed/partial/failed) + updated_at (staleness signal); when terminal, `results[]` carries per-item outcomes in submission order — each identical to the sync response modulo request_id, or an item-level error. A job-level `error` is present only on status=failed (e.g. storage_limit_exceeded). Org-scoped: a job is only visible to the org that created it.\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","example":"scb_…"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Batch job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningBatchStatus"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such job for this org","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Job store unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/portfolios":{"post":{"operationId":"createPortfolio","tags":["Portfolios"],"description":"Create a new portfolio.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Portfolio name (required)"},"description":{"type":"string","maxLength":2000,"description":"Optional description"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value metadata (max 50 keys)"}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Portfolio created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Portfolio"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict. Either a portfolio of that name already exists (`conflict`), or the organization is at its plan's portfolio limit (`resource_quota_exceeded`, `quota_scope: \"portfolios\"`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Another portfolio create for this organization is in progress and this request could not take the lock within 2 seconds (`service_unavailable`). Retryable — nothing was written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"x-signa-credits":{"credits":1,"unit":"per_request","action":"read","status":"available"}},"get":{"operationId":"listPortfolios","tags":["Portfolios"],"description":"List the organization's portfolios.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","enum":["-created_at","created_at","-updated_at","updated_at","-name","name"],"description":"Sort field with optional - prefix for descending. Default: -created_at"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"List of portfolios","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioList"}}}},"400":{"description":"Validation error (unsupported `sort`, out-of-range `limit`, or an unusable `cursor`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/portfolios/{id}":{"get":{"operationId":"retrievePortfolio","tags":["Portfolios"],"description":"Retrieve a portfolio with embedded trademarks list. Use ?limit=0 to skip trademarks.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Portfolio ID (ptf_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":100,"default":20,"description":"Number of trademarks to include (0 to skip, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for paginating trademarks within the portfolio"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Restrict the embedded trademarks list to the membership carrying this external reference. References are unique within a portfolio, so this returns at most one row. Compared with case-sensitive byte equality after trimming.","example":"ACME-2024-001"},"required":false,"name":"external_ref","in":"query"}],"responses":{"200":{"description":"Portfolio detail with embedded marks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortfolioDetail"}}}},"304":{"description":"Not modified"},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}},"patch":{"operationId":"updatePortfolio","tags":["Portfolios"],"description":"Update a portfolio. Metadata uses merge semantics (null values remove keys).\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per request.","parameters":[{"schema":{"type":"string","description":"Portfolio ID (ptf_...)"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"New portfolio name"},"description":{"type":["string","null"],"maxLength":2000,"description":"New description (null to clear)"},"metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":"Metadata patch (null values remove keys)"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated portfolio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Portfolio"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (duplicate name)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Another portfolio update for this organization is in progress and this request could not take the lock within 2 seconds (`service_unavailable`). Retryable — nothing was written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_request","action":"read","status":"available"}},"delete":{"operationId":"deletePortfolio","tags":["Portfolios"],"description":"Delete a portfolio. Cascades portfolio_marks.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per request.","parameters":[{"schema":{"type":"string","description":"Portfolio ID (ptf_...)"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"200":{"description":"Portfolio deleted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["portfolio"]},"deleted":{"type":"boolean","enum":[true]},"request_id":{"type":"string"}},"required":["id","object","deleted","request_id"]}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Portfolio is referenced by active webhook endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Another portfolio update for this organization is in progress and this request could not take the lock within 2 seconds (`service_unavailable`). Retryable — nothing was written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_request","action":"read","status":"available"}}},"/v1/portfolios/{id}/trademarks":{"post":{"operationId":"addPortfolioTrademarks","tags":["Portfolios"],"description":"Add trademarks to a portfolio. Supply exactly one of `trademark_ids` (plain ids) or `items` (ids plus optional external references) — a body carrying both is rejected. Idempotent per DISTINCT input trademark: a mark already in the portfolio is reported under `already_in_portfolio` and is not re-added. Any 409 aborts the whole batch; unknown ids are lenient and counted under `not_found`.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per request.","parameters":[{"schema":{"type":"string","description":"Portfolio ID (ptf_...)"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"trademark_ids":{"type":"array","items":{"type":"string","pattern":"^tm_"},"minItems":1,"maxItems":100,"description":"Trademark IDs to add (1-100). LENIENT on duplicates: a repeated id is silently deduplicated, and every membership is created with external_ref = null. Mutually exclusive with `items`.","example":["tm_abc123"]},"items":{"type":"array","items":{"type":"object","properties":{"trademark_id":{"type":"string","pattern":"^tm_","example":"tm_abc123"},"external_ref":{"type":"string","minLength":1,"maxLength":255,"description":"Your own docketing reference for this membership. Unique within the portfolio, compared with case-sensitive byte equality after trimming. Immutable once set: binding a different reference to the same trademark is a 409 external_ref_conflict (remove the trademark and add it again to rebind). Attaching a reference to a membership that has none is allowed.","example":"ACME-2024-001"}},"required":["trademark_id"],"additionalProperties":false},"minItems":1,"maxItems":100,"description":"Trademarks to add, each optionally carrying an external_ref (1-100). STRICT on duplicates: a repeated trademark_id, or a repeated external_ref, is a 400 validation_error — an explicit request that binds one mark to two references has no defensible resolution. Mutually exclusive with `trademark_ids`."}},"additionalProperties":false,"oneOf":[{"required":["trademark_ids"]},{"required":["items"]}]}}}},"responses":{"200":{"description":"Trademarks add result","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["portfolio_marks_result"]},"added":{"type":"integer"},"already_in_portfolio":{"type":"integer"},"not_found":{"type":"integer"},"request_id":{"type":"string"}},"required":["object","added","already_in_portfolio","not_found","request_id"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — an external reference is already bound to a different trademark in this portfolio, or this trademark already carries a different reference (`external_ref_conflict`); the batch would take the organization past its managed-marks allowance (`resource_quota_exceeded`, `quota_scope: \"managed_marks\"`); or the Idempotency-Key was reused with a different body (`conflict`). The whole batch is rolled back.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Another portfolio update for this organization is in progress and this request could not take the lock within 2 seconds (`service_unavailable`). Retryable — nothing was written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_request","action":"read","status":"available"}}},"/v1/portfolios/{id}/trademarks/remove":{"post":{"operationId":"removePortfolioTrademarks","tags":["Portfolios"],"description":"Remove trademarks from a portfolio. Supply exactly one of `trademark_ids` or `external_refs` — a body carrying both is rejected. Uses POST to avoid proxy issues with DELETE bodies.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per request.","parameters":[{"schema":{"type":"string","description":"Portfolio ID (ptf_...)"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"trademark_ids":{"type":"array","items":{"type":"string","pattern":"^tm_"},"minItems":1,"maxItems":100,"description":"Trademark IDs to remove (1-100). LENIENT on duplicates: a repeated id is silently deduplicated. Unknown ids simply match nothing. Mutually exclusive with `external_refs`.","example":["tm_abc123"]},"external_refs":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"minItems":1,"maxItems":100,"description":"External references to remove (1-100), for callers that only know their own docketing key. LENIENT on duplicates: a repeated reference is silently deduplicated. Unknown references match nothing. References are scoped to this portfolio, so another org's reference can never match. Mutually exclusive with `trademark_ids`.","example":["ACME-2024-001"]}},"additionalProperties":false,"oneOf":[{"required":["trademark_ids"]},{"required":["external_refs"]}]}}}},"responses":{"200":{"description":"Trademarks remove result","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["portfolio_marks_result"]},"removed":{"type":"integer"},"request_id":{"type":"string"}},"required":["object","removed","request_id"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict — the Idempotency-Key was reused with a different request target or body (`conflict`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Another portfolio update for this organization is in progress and this request could not take the lock within 2 seconds (`service_unavailable`). Retryable — nothing was written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_request","action":"read","status":"available"}}},"/v1/portfolios/{id}/deadlines":{"get":{"operationId":"listPortfolioDeadlines","tags":["Portfolios"],"description":"Computed deadlines across all marks in the portfolio.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":"string","description":"Portfolio ID (ptf_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["renewal","declaration_of_use","combined_renewal_and_use","declaration_of_incontestability","restoration","international_renewal","post_registration_oa_response"]},"maxItems":100,"description":"Deadline types"},"required":false,"name":"type","in":"query","style":"form","explode":false},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive due-date cutoff. ISO 8601 calendar date, `YYYY-MM-DD`; any other format is rejected with 400 `validation_error`. Defaults to 720 days after the pinned computation date; schedules use a five-year horizon, and a later `due_before` adds a `horizon_truncated` entry to `warnings`.","example":"2027-06-30"},"required":false,"name":"due_before","in":"query"},{"schema":{"type":"string","enum":["critical","upcoming","routine","in_grace","missed"]},"required":false,"name":"urgency","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque signed seek cursor. Pins as_of and binds the selector and filters; underlying records may change."},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Portfolio deadlines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeadlineListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Portfolio too large for deadline computation (`portfolio_too_large`). Deadlines are computed on demand across every mark in the portfolio, which is capped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/portfolios/{id}/deadlines.ics":{"get":{"operationId":"portfolioDeadlinesICal","tags":["Portfolios"],"description":"Download the portfolio's deadlines as an iCal (RFC 5545) calendar file. Authenticated one-time download served as an attachment, not a subscribable calendar URL.\n\nCredits: 1 per request.","parameters":[{"schema":{"type":"string","description":"Portfolio ID (ptf_...)"},"required":true,"name":"id","in":"path"},{"schema":{"type":["array","null"],"items":{"type":"integer"},"maxItems":100,"description":"Comma-separated reminder day offsets (1-3650, default: 90,30,7)"},"required":false,"name":"reminder_days","in":"query","style":"form","explode":false}],"responses":{"200":{"description":"iCal calendar file (attachment download)","content":{"text/calendar":{"schema":{"type":"string"}}}},"400":{"description":"Invalid ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Portfolio too large for deadline computation (`portfolio_too_large`). The same cap as the JSON deadlines route — this path computes the identical deadline set before rendering it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_request","action":"read","status":"available"}}},"/v1/alerts":{"get":{"operationId":"listAlerts","tags":["Alerts"],"description":"List alerts for the calling org. Opaque cursor pagination, max 100/page.\n\nCredits: 0 per request.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque pagination cursor"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["normal","high","critical"],"description":"Filter by severity"},"required":false,"name":"severity","in":"query"},{"schema":{"type":"string","enum":["trademark.created","trademark.updated","trademark.status_changed","trademark.retracted","trademark.corrected"],"description":"Filter by event type"},"required":false,"name":"event_type","in":"query"},{"schema":{"type":"string","enum":["all","current"],"description":"Scope to evaluation epoch. `current` returns only alerts from each watch's current evaluation_epoch (i.e. emitted under the watch's current query revision). `all` (default) returns alerts from every epoch."},"required":false,"name":"epoch","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by the late-alert flag. `true` returns only alerts detected late (generated after a pipeline stall recovery); `false` only fresh alerts. Omit for both."},"required":false,"name":"detected_late","in":"query"}],"responses":{"200":{"description":"Alert list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"delivery","status":"available"}}},"/v1/alerts/{id}":{"get":{"operationId":"retrieveAlert","tags":["Alerts"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Alert detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alert"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"delivery","status":"available"},"description":"Credits: 0 per request."}},"/v1/watches/{id}/alerts":{"get":{"operationId":"listWatchAlerts","tags":["Alerts"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque pagination cursor"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["all","current"],"description":"Scope to evaluation epoch. `current` returns only alerts emitted under the watch's current evaluation_epoch (i.e. its current query revision). `all` (default) returns alerts from every epoch."},"required":false,"name":"epoch","in":"query"}],"responses":{"200":{"description":"Alert list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}},"description":"Credits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate."}},"/v1/alerts/lookup":{"post":{"operationId":"lookupAlerts","tags":["Alerts"],"description":"Bulk-fetch alerts by ID for polling clients. Capped at 100 IDs per call. Org-scoped — alerts belonging to other orgs are silently dropped from the result (no info disclosure).\n\nCredits: 0 per request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100}},"required":["ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Lookup result","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"alt_01HK..."},"object":{"type":"string","enum":["alert"]},"schema_version":{"type":"string","enum":["2026-06-01"]},"watch":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["mark","portfolio","owner","class","similarity"]}},"required":["id","name","type"]},"customer_reference":{"type":["string","null"],"description":"Customer passthrough set on the watch; null if unset."},"event":{"type":"object","properties":{"type":{"type":"string","enum":["trademark.created","trademark.updated","trademark.status_changed","trademark.retracted","trademark.corrected"]},"summary":{"type":"string","description":"Short human-readable description, e.g. \"Status changed: pending → registered\"."},"diff":{"type":"array","items":{"$ref":"#/components/schemas/AlertDiffEntry"},"description":"Field-level change diff. Entry `path` values are the underlying flat change-tracking field tokens (e.g. `status_primary`) and intentionally differ from the nested `trademark` object keys (e.g. `status.primary`); treat them as opaque field identifiers."},"diff_truncated":{"type":"boolean","description":"Present and `true` when the change diff was bounded (entries dropped past the max count, or an over-long from/to value replaced with a sentinel, or a byte-budget cap hit). Absent when the diff is complete."}},"required":["type","summary","diff"]},"match":{"type":["object","null"],"properties":{"reason":{"type":["string","null"]},"score":{"type":["number","null"]},"score_basis":{"type":["string","null"]},"tier":{"type":["string","null"],"enum":["identical","near_identical","similar","related",null],"description":"Similarity tier of the matched mark, the same label a search hit carries as `match.tier` (identical, near_identical, similar, related). A retrieval category, not a measured edit distance. Null for filter-only watches, marks found only by their number, and alerts emitted before the field existed."}},"required":["reason","score","score_basis","tier"],"description":"Match metadata (why/how the mark matched the watch). Null for pure-filter / pre-v2 alerts that carry no match scoring. `score` is the engine score for the watch query, not the 0-100 search `relevance_score`."},"trademark":{"$ref":"#/components/schemas/AlertTrademark"},"deadline":{"type":"object","properties":{"severity":{"type":"string","enum":["normal","high","critical"]},"opposition_window_status":{"type":["string","null"],"enum":["open","closing_soon","critical","closed",null]},"must_act_by":{"type":["string","null"]},"must_act_by_adjustment":{"type":["string","null"],"enum":["moved","unchanged","not_checked","month_end_overflow",null],"description":"Whether a holiday calendar stood behind `must_act_by` when it was frozen onto this alert. `not_checked` means no pinned closure list verified the date: the close fell outside the office calendar’s pinned coverage years (the deterministic weekend and fixed-holiday roll may still have been applied), or the rule carries no calendar. The true close can only be the same or LATER, so a `not_checked` date is correct-or-EARLY and must not be diarised as final. Null on alerts emitted before this field existed and on alerts with no opposition window.","example":null}},"required":["severity","opposition_window_status","must_act_by","must_act_by_adjustment"]},"detected_late":{"type":"boolean","description":"True when this alert was generated well after the underlying change occurred (e.g. the monitoring pipeline recovered from a stall and processed backlogged changes). Late alerts remain fully visible here but are excluded from webhook delivery by default."},"timestamps":{"type":"object","properties":{"occurred_at":{"type":["string","null"]},"ingested_at":{"type":"string","description":"When the underlying change was ingested. Omitted when no change row is linked."},"created_at":{"type":"string"}},"required":["occurred_at","created_at"]},"links":{"type":"object","properties":{"trademark":{"type":"string"},"watch":{"type":"string"}},"required":["trademark","watch"]},"evaluation_epoch":{"type":"integer"},"provenance":{"type":"object","properties":{"sync_run":{"type":"string","description":"Ingestion run that detected this alert (prefixed sync_run ID). Omitted when the alert has no linked run (pre-provenance / unbacked rows).","example":"srun_01HK..."},"content_version":{"type":"integer","description":"The trademark_record.version the alert froze at."},"detection_latency_seconds":{"type":["integer","null"],"description":"created_at − occurred_at, in seconds. Null when the source-published time (occurred_at) is unknown or in the future relative to created_at (never negative)."},"late_detection":{"type":"boolean","description":"True when detection latency exceeded the internal per-office SLO. False whenever latency is unknown (never flags lateness that cannot be proven)."}},"required":["content_version","detection_latency_seconds","late_detection"],"description":"Evidence chain for the alert: which ingestion run detected it, the content version, and the office-published → detected latency with lateness flagged."}},"required":["id","object","schema_version","watch","customer_reference","event","match","trademark","deadline","detected_late","timestamps","links","evaluation_epoch","provenance"]}},"request_id":{"type":"string"}},"required":["object","data","request_id"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"delivery","status":"available"}}},"/v1/watches":{"post":{"operationId":"createWatch","tags":["Watches"],"description":"Create a new watch. Resource quota (per-plan watches.maxResources) is enforced; the legacy per-request quota is not. The `query.filters` vocabulary is the camelCase SearchFiltersV2 key set, plus the entity-watch fields: `entityId` (a single resolved entity — `ent_*` id or raw UUID — matching every trademark whose current owners belong to that entity, including owners linked later) and `entityGroup` (the entity's whole GLEIF corporate family: parent + all subsidiaries, resolved at each evaluation so newly-linked family members are picked up automatically). The two are mutually exclusive (400 when both are present); a nonexistent/suppressed entity target returns 400, and a corporate family exceeding the relationship-graph walk limit returns 422 `entity_too_large`.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"watch_type":{"type":"string","enum":["mark","portfolio","owner","class","similarity"]},"query":{"type":"object","additionalProperties":{},"description":"Watch query JSON (max 50,000 bytes serialized, depth 5; larger bodies are 400 `validation_error`). `version` is required: `v1`, `v2` and `v3` are accepted, and a new or changed query is stored as a v3 similarity watch whatever `version` it sends (`version` is set to `v3`) unless it uses the deprecated keys below: `q` (string), optional `similarity` (the search channels: `identical`, `fuzzy`, `embedded`, `phonetic`, `lookalike`; default `identical,fuzzy,embedded,lookalike`, `identical` always on), optional `min_tier` (the weakest similarity tier that alerts: `identical`, `near_identical`, `similar`, `related`; default `related`, everything through), `filters`, and optional `trigger_events` (default: `trademark.created`, `trademark.updated`, `trademark.status_changed`; `trademark.retracted` / `trademark.corrected` are opt-in; `trademark.corrected` also covers a status Signa corrected, including a lapse or a reversal shown by office records that reached Signa late, which then never arrives as `trademark.status_changed` / `trademark.updated`). The search text filters (`mark_text_*`) and exclusions (`exclude`, `*_not`) are not accepted on watches. Deprecated until 2026-12-28: `strategies` (replaced by `similarity`) and `min_match_tier` (replaced by `min_tier`). A write that uses them is kept as a legacy watch with its original matching until it is re-saved without them, and each is reported in the response `deprecations`; sending old and new keys together is 400 `conflicting_params`. Stored watches keep the matching they were saved with; a PATCH whose query equals the stored one changes nothing, one that differs only where a write normalises it (such as offices added from jurisdictions, or code and ID casing) is saved in that form and not migrated (a legacy watch stays legacy), though the saved form can change what it matches (a jurisdictions-only watch is evaluated once offices are added), and a PATCH that changes it re-saves it under these rules. `filters.offices` takes WIPO ST.3 codes (`US`, `EM`, …; legacy `uspto`/`euipo`/`EU` accepted); `filters.jurisdictions` without `filters.offices` is auto-translated to the live offices for those jurisdictions and is rejected with 400 `no_live_office` when none resolves. `score_threshold` is NOT accepted on write (400), since match scores are informational via `match.score` on alerts, and is never echoed on read.","example":{"version":"v3","q":"acme","similarity":["identical","fuzzy","phonetic"],"min_tier":"similar","filters":{"offices":["US"],"niceClasses":[9]}}},"delivery_mode":{"type":"string","enum":["always_per_alert"]},"customer_reference":{"type":["string","null"],"maxLength":200,"description":"Optional customer passthrough echoed onto every alert this watch produces. Max 200 characters.","example":"PO-4242"},"metadata":{"type":"object","additionalProperties":{}}},"required":["name","watch_type"],"additionalProperties":false}}}},"responses":{"201":{"description":"Watch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Watch"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits — `insufficient_credits_for_watch`: the pooled credit balance cannot fund the minimum monitoring window for a new watch (charged plans only). Extensions carry `credit_balance`, `credit_required`, `monitoring_daily_cost`, `required_days`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large — the 256KB service-level query cap. NOT reachable over HTTP: the 50,000-byte / depth-5 bounded-JSON check on `query` runs first and answers 400 `validation_error`; only service/MCP callers can observe this status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Entity group too large (filters.entityGroup family-graph walk cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Another watch create for this organization is in progress and this request could not take the lock within 2 seconds (`service_unavailable`). Retryable — nothing was written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}},"get":{"operationId":"listWatches","tags":["Watches"],"description":"List watches for the calling organization. NOTE: `alert_count_24h` is always `null` in list responses to avoid N+1 query cost; call `GET /v1/watches/{id}` to retrieve the 24h alert count for a specific watch.\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque pagination cursor"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["active","paused"],"description":"Filter by status (active or paused)."},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Watch list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}}},"/v1/watches/{id}":{"get":{"operationId":"retrieveWatch","tags":["Watches"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Watch detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Watch"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}},"description":"Credits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate."},"patch":{"operationId":"updateWatch","tags":["Watches"],"description":"Update a watch. Replacing `query` re-validates it under the same rules as create — including the entity-watch fields `filters.entityId` / `filters.entityGroup` (mutually exclusive; nonexistent/suppressed entity → 400; over-cap GLEIF family → 422 `entity_too_large`) — and bumps the evaluation epoch so the new criteria apply from the next ingestion sync forward.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"query":{"type":"object","additionalProperties":{}},"delivery_mode":{"type":"string","enum":["always_per_alert"]},"status":{"type":"string","enum":["active","paused"]},"customer_reference":{"type":["string","null"],"maxLength":200,"description":"Customer passthrough echoed onto alerts. Send a string to set, `null` to clear, omit to leave unchanged. Max 200 characters.","example":"PO-4242"},"metadata":{"type":"object","additionalProperties":{}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Watch"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits to fund the minimum monitoring window for newly added distinct trademarks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large — the 256KB service-level query cap. NOT reachable over HTTP: the 50,000-byte / depth-5 bounded-JSON check on `query` runs first and answers 400 `validation_error`; only service/MCP callers can observe this status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Entity group too large (filters.entityGroup family-graph walk cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}},"delete":{"operationId":"deleteWatch","tags":["Watches"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"200":{"description":"Watch soft-deleted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["watch"]},"deleted":{"type":"boolean","enum":[true]},"request_id":{"type":"string"}},"required":["id","object","deleted","request_id"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"This operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}}},"/v1/watches/{id}/diagnostics":{"get":{"operationId":"getWatchDiagnostics","tags":["Watches"],"description":"Audit-mode provenance for a single (watch, trademark) pair. Returns an 11-field explainable trace covering candidacy, trigger filter, match outcome, lease state, epoch provenance, opposition citation, and retention windows. Enabled by default; ops can kill-switch via MONITORING_DIAGNOSTICS_ENABLED=false (returns 404 when off). Cross-org references return 404. An unknown trademark on your own watch returns 404 naming the trademark. `reason` names the first step that stopped an alert, ending in `mark did not match the watch query or filters` when the change was evaluated and wanted.\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Prefixed trademark ID (tm_...)"},"required":true,"name":"trademark_id","in":"query"}],"responses":{"200":{"description":"Diagnostics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchDiagnostics"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}}},"/v1/watches/{id}/attestation":{"get":{"operationId":"getWatchAttestation","tags":["Watches"],"description":"Monthly proof-of-monitoring artifact for a closed UTC calendar month, computed deterministically from the evaluation receipts spine. Defaults to the previous month. The current (open) month returns 422 attestation_period_open unless `partial=true`. Periods beyond the 25-month retention window return 410 attestation_expired. A scope with no supported (ingested) offices returns 422 attestation_unsupported_scope. A month that ended before the watch was created, with no evaluations recorded in it, returns 422 period_before_watch; in the month the watch was created, gaps start at its creation time. Cross-org / unknown watches return 404. Request the PDF business record with `?format=pdf` or `Accept: application/pdf`.\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"UTC calendar month YYYY-MM. Default: previous month."},"required":false,"name":"period","in":"query"},{"schema":{"type":"string","enum":["json","pdf"],"description":"Response format. Default json; pdf returns the business record."},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Set true to allow an interim artifact for the current open month."},"required":false,"name":"partial","in":"query"}],"responses":{"200":{"description":"Attestation (JSON or PDF)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchAttestation"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Attestation evidence expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Period still open, period ended before the watch was created, or no supported offices in scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}}},"/v1/watches/{id}/pause":{"post":{"operationId":"pauseWatch","tags":["Watches"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"200":{"description":"Paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Watch"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"This operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}}},"/v1/watches/{id}/resume":{"post":{"operationId":"resumeWatch","tags":["Watches"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"200":{"description":"Resumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Watch"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"This operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}}},"/v1/watches/preview":{"post":{"operationId":"previewWatch","tags":["Watches"],"description":"Dry-run watch evaluation. Returns the count of trademarks that would alert if this query were created today, plus a page of the actual matching marks in the canonical trademark summary shape (same serialization as GET /v1/trademarks). Set `count_only: true` to skip the marks and get just the number. Evaluates the watch query (q, strategies, min_match_tier, filters, trigger_events) over the trial window with the same match gate as live watches, with no DB writes (VAL-API-011). Watches with a text query are searched first and the matches are intersected with the window's changes; results are ordered by relevance. A watch without a text query whose window holds more changes than the preview checks runs its filters the same way, so class and owner filters always apply. Unknown owner, attorney or firm IDs and Nice classes outside 1-45 return 400, as on create.\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"object","additionalProperties":{}},"trial_window_days":{"type":"integer","minimum":1,"maximum":365},"count_only":{"type":"boolean"},"result_limit":{"type":"integer","minimum":1,"maximum":50}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"Preview result","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["watch_preview"]},"estimated_match_count":{"type":"integer"},"trial_window_days":{"type":"integer"},"similarity_applied":{"type":["array","null"],"items":{"type":"string","enum":["identical","fuzzy","embedded","phonetic","lookalike"]},"description":"The similarity channels the text query ran (identical always included). Null when the query has no q, and for a query that uses the deprecated keys (previewed as the legacy watch a create would keep)."},"min_tier":{"type":["string","null"],"enum":["identical","near_identical","similar","related",null],"description":"The weakest similarity tier that alerts (`related` admits everything). Null for a query that uses the deprecated keys, which keeps its `min_match_tier`."},"deprecations":{"type":"array","items":{"$ref":"#/components/schemas/WatchDeprecation"},"description":"Present when the previewed query used a deprecated key (`strategies`, `min_match_tier`); the preview ran it as the legacy watch a create would keep."},"estimate_basis":{"type":"string","enum":["candidacy_upper_bound","query_upper_bound","lower_bound"],"description":"Present only when estimated_match_count is not an exact count. `query_upper_bound`: the time budget ran out after the search but before the change check; the count is the marks that matched the query in the window plus the marks changed in the last 6 hours that the search index may not reflect yet, so it can only be too high. `lower_bound`: the search timed out or lost a shard, more than 10,000 marks matched the query in the window, the change check timed out, or the re-check of marks changed in the last 6 hours (which the search index may not reflect yet) could not finish; the count is the verified matches (0 if none), so it can only be too low. `candidacy_upper_bound`: a watch without a text query could not be fully evaluated (search unreachable or the budget ran out), or a watch scoped only by offices or trademark IDs changed more marks than the preview checks; the count is the number of changed marks in scope in the window. A watch without a text query whose other filters (classes, owners, statuses and so on) cover a very large change set is previewed like a text watch: its filters run as the search, so the count is exact or a `lower_bound`."},"partial":{"type":"boolean","description":"Present and true when the preview did not finish: the server-side time budget ran out, the search timed out or lost a shard, filters could not be checked, or the results page could not be loaded (results is then empty and has_more false, but the count stands). estimated_match_count and estimate_basis describe what was evaluated; results holds verified matches only."},"results":{"type":"array","items":{"$ref":"#/components/schemas/TrademarkSummaryV1"},"description":"A page of matching trademarks (summary shape), up to result_limit. Returned by default; omitted when count_only was set on the request."},"has_more":{"type":"boolean","description":"Whether more matches exist beyond the returned `results` page. Returned by default; omitted when count_only was set."},"result_limit":{"type":"integer","description":"Echo of the effective results page size. Returned by default; omitted when count_only was set."},"request_id":{"type":"string"}},"required":["object","estimated_match_count","trial_window_days","similarity_applied","min_tier","request_id"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large — the 256KB service-level query cap. NOT reachable over HTTP: the 50,000-byte / depth-5 bounded-JSON check on `query` runs first and answers 400 `validation_error`; only service/MCP callers can observe this status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Entity group too large (filters.entityGroup family-graph walk cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Concurrency limit — another preview is already running for this organization (or the instance-wide preview limit is saturated). `rate_limited` envelope; honor the `Retry-After` header (≈ the server-side preview budget).","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until a preview slot is expected to free up."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Search is unavailable, so a watch with a text query cannot be evaluated, nor a watch without one whose window holds more changes than the preview checks one by one and whose filters go beyond offices or trademark IDs (it is searched by its filters). `service_unavailable`, retryable; honor `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Preview timeout — the server-side time budget (or the database statement timeout) expired before any usable candidacy result existed. `preview_timeout` envelope with `retryable: false`; narrow the query instead of retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}}},"/v1/watches/bulk":{"post":{"operationId":"bulkCreateWatches","tags":["Watches"],"description":"Create up to 100 watches in one call. Counts against per-plan watches.maxResources. All or nothing: when any item fails validation, nothing is created and the 400 lists every failing item, each `errors[].field` prefixed with the item index (`watches[3].query.q`).\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"watches":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"watch_type":{"type":"string","enum":["mark","portfolio","owner","class","similarity"]},"query":{"type":"object","additionalProperties":{},"description":"Watch query JSON (max 50,000 bytes serialized, depth 5; larger bodies are 400 `validation_error`). `version` is required: `v1`, `v2` and `v3` are accepted, and a new or changed query is stored as a v3 similarity watch whatever `version` it sends (`version` is set to `v3`) unless it uses the deprecated keys below: `q` (string), optional `similarity` (the search channels: `identical`, `fuzzy`, `embedded`, `phonetic`, `lookalike`; default `identical,fuzzy,embedded,lookalike`, `identical` always on), optional `min_tier` (the weakest similarity tier that alerts: `identical`, `near_identical`, `similar`, `related`; default `related`, everything through), `filters`, and optional `trigger_events` (default: `trademark.created`, `trademark.updated`, `trademark.status_changed`; `trademark.retracted` / `trademark.corrected` are opt-in; `trademark.corrected` also covers a status Signa corrected, including a lapse or a reversal shown by office records that reached Signa late, which then never arrives as `trademark.status_changed` / `trademark.updated`). The search text filters (`mark_text_*`) and exclusions (`exclude`, `*_not`) are not accepted on watches. Deprecated until 2026-12-28: `strategies` (replaced by `similarity`) and `min_match_tier` (replaced by `min_tier`). A write that uses them is kept as a legacy watch with its original matching until it is re-saved without them, and each is reported in the response `deprecations`; sending old and new keys together is 400 `conflicting_params`. Stored watches keep the matching they were saved with; a PATCH whose query equals the stored one changes nothing, one that differs only where a write normalises it (such as offices added from jurisdictions, or code and ID casing) is saved in that form and not migrated (a legacy watch stays legacy), though the saved form can change what it matches (a jurisdictions-only watch is evaluated once offices are added), and a PATCH that changes it re-saves it under these rules. `filters.offices` takes WIPO ST.3 codes (`US`, `EM`, …; legacy `uspto`/`euipo`/`EU` accepted); `filters.jurisdictions` without `filters.offices` is auto-translated to the live offices for those jurisdictions and is rejected with 400 `no_live_office` when none resolves. `score_threshold` is NOT accepted on write (400), since match scores are informational via `match.score` on alerts, and is never echoed on read.","example":{"version":"v3","q":"acme","similarity":["identical","fuzzy","phonetic"],"min_tier":"similar","filters":{"offices":["US"],"niceClasses":[9]}}},"delivery_mode":{"type":"string","enum":["always_per_alert"]},"customer_reference":{"type":["string","null"],"maxLength":200,"description":"Optional customer passthrough echoed onto every alert this watch produces. Max 200 characters.","example":"PO-4242"},"metadata":{"type":"object","additionalProperties":{}}},"required":["name","watch_type","query"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["watches"],"additionalProperties":false}}}},"responses":{"200":{"description":"Bulk-create result","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"wat_01HK..."},"object":{"type":"string","enum":["watch"]},"name":{"type":"string"},"watch_type":{"type":"string","enum":["mark","portfolio","owner","class","similarity"]},"query":{"type":"object","additionalProperties":{}},"delivery_mode":{"type":"string","enum":["always_per_alert","digest_above_threshold","digest_only"]},"status":{"type":"string","enum":["active","paused","disabled","paused_insufficient_credits"]},"alert_count_24h":{"type":["integer","null"],"description":"Number of alerts the watch has generated in the last 24 hours. **Only populated on GET /v1/watches/{id}**; always `null` on list responses (`GET /v1/watches`) to avoid an N+1 query per row. Call the GET-by-id endpoint to retrieve the count for a specific watch."},"health_status":{"type":["string","null"],"enum":["healthy","pending","lagging","degraded","unsupported","paused",null],"description":"Honest health state of the watch: healthy | pending | lagging | degraded | unsupported | paused. Populated on `GET /v1/watches` (list) and `GET /v1/watches/{id}`; `null` on create/update responses. `unsupported` means the watch scope includes an office Signa does not ingest — it never reads as healthy-with-zero-alerts. Precedence: paused > unsupported > degraded > lagging > pending > healthy."},"health":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["healthy","pending","lagging","degraded","unsupported","paused"]},"evaluated_at":{"type":["string","null"],"description":"Max last_evaluated_at (evaluation wall-clock) across in-scope offices."},"evaluations_30d":{"type":["integer","null"]},"issues":{"type":"array","items":{"type":"string","enum":["office_lagging","evaluation_backlog","failing","unresolved_target","never_evaluated","unsupported_office","config_changed_pending","invalid_filter"]},"description":"Distinct issues across the watch: every per-office `issue`, plus `invalid_filter` when the stored `niceClasses` include a value outside 1-45 (saved before that check existed). Remove the value with PATCH /v1/watches/{id}."},"offices":{"type":"array","items":{"type":"object","properties":{"office_code":{"type":"string","description":"WIPO ST.3 office code (uppercase, e.g. `US`, `EM`).","example":"US"},"status":{"type":"string","description":"ok when the office is healthy, otherwise the issue slug."},"coverage_through":{"type":["string","null"],"description":"Office-DATA timestamp through which this watch has been evaluated for this office (frozen at evaluation time — NOT wall-clock). Stops advancing when the office lags; null before the first evaluation or for unsupported offices."},"coverage_basis":{"type":["string","null"],"enum":["source_dates","date_range","run_completed",null],"description":"Which derivation rung produced coverage_through: source_dates (strongest) > date_range > run_completed (weakest)."},"last_evaluated_at":{"type":["string","null"],"description":"Evaluation wall-clock (when the evaluator last ran) — NOT a coverage claim."},"evaluations_30d":{"type":["integer","null"],"description":"Count of evaluations (receipts) for this office over the trailing 30 days. Null on list rows."},"issue":{"type":["string","null"],"enum":["office_lagging","evaluation_backlog","failing","unresolved_target","never_evaluated","unsupported_office","config_changed_pending",null]},"last_error":{"type":["string","null"],"description":"Sanitized classification of the last evaluation error (never a raw error string): entity_unresolved, entity_group_too_large, opensearch_query_rejected, budget_declined (the last sync run for this office was declined over the live-candidate budget and was NOT evaluated for this watch — an operator re-drive is required), or internal_evaluation_error."}},"required":["office_code","status","coverage_through","coverage_basis","last_evaluated_at","evaluations_30d","issue","last_error"]}}},"required":["status","evaluated_at","evaluations_30d","issues","offices"],"description":"Full health object with per-office coverage and issues. **Only populated on GET /v1/watches/{id}**; `null` on list responses (batched to two extra queries per page). Health certifies that evaluation occurred through the stated office-data horizon; it does not certify that every relevant mark was surfaced (bounded by search strategy + connector coverage)."},"last_alerted_at":{"type":["string","null"]},"customer_reference":{"type":["string","null"],"description":"Customer-supplied passthrough string echoed verbatim onto every alert this watch produces (`data.customer_reference`). `null` when unset. Set/clear it via POST/PATCH /v1/watches.","example":"PO-4242"},"metadata":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deprecations":{"type":"array","items":{"$ref":"#/components/schemas/WatchDeprecation"},"description":"Present on create, update and bulk responses when the written query used a deprecated key: `strategies` (replaced by `similarity`) or `min_match_tier` (replaced by `min_tier`). The watch is kept as a legacy watch with its original matching until it is re-saved without them. Each entry names the key, its replacement and the date the old key stops being accepted."}},"required":["id","object","name","watch_type","query","delivery_mode","status","alert_count_24h","health_status","health","last_alerted_at","customer_reference","metadata","created_at","updated_at"]}},"request_id":{"type":"string"}},"required":["object","data","request_id"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits — `insufficient_credits_for_watch`: the pooled credit balance cannot fund the minimum monitoring window for a new watch (charged plans only). Extensions carry `credit_balance`, `credit_required`, `monitoring_daily_cost`, `required_days`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Resource quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large — the 256KB service-level query cap. NOT reachable over HTTP: the 50,000-byte / depth-5 bounded-JSON check on `query` runs first and answers 400 `validation_error`; only service/MCP callers can observe this status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Entity group too large (filters.entityGroup family-graph walk cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Another watch create for this organization is in progress and this request could not take the lock within 2 seconds (`service_unavailable`). Retryable — nothing was written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}}},"/v1/monitoring/status":{"get":{"operationId":"getMonitoringStatus","tags":["Watches"],"description":"Org-level monitoring program status: a health aggregate over all of the org watches, GLOBAL per-live-office pipeline freshness, and the continuous pipeline-verification gauges. The pipeline timestamps are null-honest: an absent or stale gauge is surfaced as null, never as a fresh verification.\n\nCredits: 1 per mark per day (free during beta). Management requests cost 0 credits; the daily monitoring meter is separate.","responses":{"200":{"description":"Monitoring status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringStatus"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"watch_status","status":"beta","charged_per_request":false,"daily":{"credits":1,"unit":"per_mark_per_day","action":"watch_status"}}}},"/v1/webhooks":{"post":{"operationId":"createWebhookEndpoint","tags":["Webhooks"],"description":"Create a webhook endpoint. The signing secret is returned ONCE in the response. Store it securely and verify HMAC signatures against it. Subsequent GET responses redact the secret. trademark.status_changed, trademark.corrected and office_action.issued are emitted only for marks in an organization portfolio; alert.created follows watch scope. An organization that monitors a mark only through watches receives alert.created, but no direct trademark event. An endpoint subscribed to trademark.status_changed also receives trademark.corrected, a correction of a status Signa published earlier.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 0 per request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"description":{"type":"string","maxLength":2000},"enabled_events":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":20,"description":"Events delivered to this endpoint. Accepted values: alert.created, trademark.status_changed, trademark.corrected, office_action.issued. trademark.status_changed, trademark.corrected and office_action.issued are delivered only for marks in one of the organization's portfolios; trademark.status_changed also delivers trademark.corrected. alert.created follows watch scope."},"portfolio_id":{"type":["string","null"],"description":"Limit this endpoint to events on marks in this portfolio (ptf_*). Applies to every event type, alert.created included: an alert is delivered only when its matched mark was a member of the portfolio at event time."},"metadata":{"type":"object","additionalProperties":{}}},"required":["url","enabled_events"],"additionalProperties":false}}}},"responses":{"201":{"description":"Endpoint created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Portfolio not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"x-signa-credits":{"credits":0,"unit":"per_request","action":"delivery","status":"available"}},"get":{"operationId":"listWebhookEndpoints","tags":["Webhooks"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque pagination cursor"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Endpoint list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"delivery","status":"available"},"description":"Credits: 0 per request."}},"/v1/webhooks/{id}":{"get":{"operationId":"retrieveWebhookEndpoint","tags":["Webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Endpoint detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"delivery","status":"available"},"description":"Credits: 0 per request."},"patch":{"operationId":"updateWebhookEndpoint","tags":["Webhooks"],"description":"Update a webhook endpoint. trademark.status_changed, trademark.corrected and office_action.issued are emitted only for marks in an organization portfolio; alert.created follows watch scope. An organization that monitors a mark only through watches receives alert.created, but no direct trademark event. An endpoint subscribed to trademark.status_changed also receives trademark.corrected, a correction of a status Signa published earlier.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 0 per request.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"description":{"type":["string","null"],"maxLength":2000},"enabled_events":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":20,"description":"Events delivered to this endpoint. Accepted values: alert.created, trademark.status_changed, trademark.corrected, office_action.issued. trademark.status_changed, trademark.corrected and office_action.issued are delivered only for marks in one of the organization's portfolios; trademark.status_changed also delivers trademark.corrected. alert.created follows watch scope."},"portfolio_id":{"type":["string","null"],"description":"Limit this endpoint to events on marks in this portfolio (ptf_*), or null to clear. Applies to every event type, alert.created included: an alert is delivered only when its matched mark was a member of the portfolio at event time."},"status":{"type":"string","enum":["active","disabled"]},"metadata":{"type":"object","additionalProperties":{}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"delivery","status":"available"}},"delete":{"operationId":"deleteWebhookEndpoint","tags":["Webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"200":{"description":"Endpoint deleted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_endpoint"]},"deleted":{"type":"boolean","enum":[true]},"request_id":{"type":"string"}},"required":["id","object","deleted","request_id"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"This operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 0 per request.","x-signa-credits":{"credits":0,"unit":"per_request","action":"delivery","status":"available"}}},"/v1/webhooks/{id}/rotate-secret":{"post":{"operationId":"rotateWebhookSecret","tags":["Webhooks"],"description":"Rotate the webhook signing secret. The new secret is returned ONCE in the response. By default the previous secret remains valid for 24 hours so customers have time to update without missing deliveries. For emergency security rotations (e.g. suspected leak mid-overlap), pass `force=true` (in the request body or as `?force=true` query param) — this immediately invalidates the previous secret and writes a `webhook.secret.force_rotated` audit log entry. Without `force`, attempting to rotate while the previous secret is still in its 24h overlap window returns 409. The optional JSON body accepts `{\"force\": boolean, \"reason\": string}` — `reason` (max 500 chars) is recorded in the `webhook.secret.force_rotated` audit event when `force=true`. The body may be omitted entirely.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 0 per request.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"anyOf":[{"type":"string","enum":["true"]},{"type":"string","enum":["false"]}],"description":"Convenience query-string alternative to `force` in the body. `?force=true` is equivalent to `{\"force\": true}` in the JSON body."},"required":false,"name":"force","in":"query"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"200":{"description":"Secret rotated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Previous-secret 24h overlap is still active and `force=true` was not passed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"delivery","status":"available"}}},"/v1/webhooks/{id}/test":{"post":{"operationId":"testWebhookEndpoint","tags":["Webhooks"],"description":"Send a synthetic webhook-event-type:ping to the endpoint. Does NOT increment consecutive_failures even if the URL is unreachable — admins should be able to test dead URLs without auto-disabling production endpoints (VAL-WEBHOOK-007).\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"202":{"description":"Test queued","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_test"]},"delivery_attempt_id":{"type":"string"},"request_id":{"type":"string"}},"required":["object","delivery_attempt_id","request_id"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Webhook is disabled — cannot enqueue test delivery against a disabled endpoint. Re-enable the endpoint (PATCH status=\"active\") before retesting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhooks"],"description":"List delivery audit rows for an endpoint. Retention: 30 days (daily-partitioned). Use `?since=` (ISO 8601) to optionally narrow the results to a time window; cursor pagination works on its own and does not require `since`.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque pagination cursor"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO 8601 timestamp; only deliveries with created_at >= this value are returned. Useful for incremental polling. Combine with cursor for stable pagination across the window.","example":"2026-05-01T00:00:00Z"},"required":false,"name":"since","in":"query"}],"responses":{"200":{"description":"Delivery list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/deliveries/{did}":{"get":{"operationId":"retrieveWebhookDelivery","tags":["Webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"did","in":"path"}],"responses":{"200":{"description":"Delivery detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}/deliveries/{did}/redeliver":{"post":{"operationId":"redeliverWebhookDelivery","tags":["Webhooks"],"description":"Manually redeliver a webhook event. Inserts a new attempt row referencing the same event_id. Only deliveries whose chain is TERMINAL are redeliverable: `delivered`, `exhausted`, or a `failed` attempt with no scheduled retry. A delivery whose automatic retry chain is still live (`pending`, or `failed` with a scheduled retry) returns 409 `redelivery_conflict` — wait for the chain to reach a terminal state (poll the delivery) before redelivering.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 0 per request.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"did","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"202":{"description":"Redelivery queued","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["webhook_redelivery"]},"delivery_attempt_id":{"type":"string"},"request_id":{"type":"string"}},"required":["object","delivery_attempt_id","request_id"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Redelivery conflict — the delivery’s automatic retry chain is still live (pending, or failed with a scheduled retry). Poll the delivery until it is terminal, then retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Redelivery conflict — the target is a `webhook.test` delivery, which cannot be redelivered. Use POST /v1/webhooks/{id}/test to send a fresh test delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":0,"unit":"per_request","action":"delivery","status":"available"}}},"/v1/events":{"get":{"operationId":"listEvents","tags":["Events"],"description":"List projected events for the authenticated organization. Cursor-based pagination. Use `sort=id` with `after` to resume replay from a durable checkpoint. Beta: the payload shape is not yet frozen — see the Events tag description.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by event type(s), case-insensitive. Comma-separated: ?event_type=alert.created,trademark.status_changed. Values: trademark.created, trademark.updated, trademark.status_changed, trademark.retracted, trademark.corrected, office_action.issued, alert.created; any other value returns 400. As on webhooks, trademark.status_changed also matches trademark.corrected (status corrections); trademark.corrected alone matches corrections only."},"required":false,"name":"event_type","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string"},"maxItems":100,"description":"Filter by office code(s). WIPO ST.3 uppercase (e.g. US, EM); legacy acronym slugs (uspto, euipo) and EU are also accepted."},"required":false,"name":"office_code","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Filter by trademark ID (tm_ prefixed)"},"required":false,"name":"trademark_id","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"ISO date or timestamp — return events recorded by Signa at or after this time"},"required":false,"name":"since","in":"query"},{"schema":{"type":"string","enum":["-id","id"],"default":"-id"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","description":"Exclusive evt_* replay checkpoint; valid only with sort=id"},"required":false,"name":"after","in":"query"},{"schema":{"type":"string","description":"Filter events by the portfolio membership snapshot taken when the event was recorded. Applies to every family, alert.created included: an alert is in the portfolio only when its matched mark was a member at event time. Later membership changes never rewrite history (requires portfolios:manage)"},"required":false,"name":"portfolio_id","in":"query"},{"schema":{"type":"string","description":"Opaque pagination cursor from the previous page"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventList"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing events:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Portfolio not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Replay checkpoint is outside the retention window","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/events/{id}":{"get":{"operationId":"retrieveEvent","tags":["Events"],"description":"Retrieve event detail with field-level before/after diffs.\n\nTrademark events include field-level diffs; alert.created events render their stored versioned payload.\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","description":"Event ID (evt_...)","example":"evt_3D7rZ9"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Event detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventDetail"}}}},"400":{"description":"Invalid event ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing events:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/organization/me":{"get":{"operationId":"getMe","tags":["Administration"],"description":"Get the authenticated identity context. Works with any valid API key.","responses":{"200":{"description":"Identity context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Identity"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateOrganization","tags":["Administration"],"description":"Update the authenticated organization. Currently supports renaming. Requires the `organization:manage` scope.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Organization display name"}},"required":["name"]}}}},"responses":{"200":{"description":"Updated organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}]}},"/v1/organization/usage":{"get":{"operationId":"getUsage","tags":["Administration"],"description":"Get current billing period usage and rate limit status. Requires the `billing:read` scope.","responses":{"200":{"description":"Usage data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization/plan":{"get":{"operationId":"getOrgPlan","tags":["Administration"],"description":"Get the organization's current plan, billing period, and per-endpoint quota breakdown.","responses":{"200":{"description":"Organization plan with quotas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgPlan"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization/api-keys":{"post":{"operationId":"createApiKey","tags":["Administration"],"description":"Create a new API key. Returns the raw key exactly once.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Key name (required)"},"scopes":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":20,"description":"Scopes for the key (must be subset of creating key's scopes)"},"expires_at":{"type":["string","null"],"description":"Expiration date (ISO 8601) or null for no expiry"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value metadata (max 50 keys)"}},"required":["name","scopes"]}}}},"responses":{"201":{"description":"API key created (includes raw key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyWithKey"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope or escalation attempt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}]},"get":{"operationId":"listApiKeys","tags":["Administration"],"description":"List API keys for the organization. Raw key is never included. Defaults to `status=active`; pass `status=revoked|expired|all` to see tombstones or audit history.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["active","revoked","expired","all"],"description":"Lifecycle filter. Defaults to \"active\" (non-revoked, non-expired, non-system keys). \"all\" includes every key — even revoked and expired — for audit use."},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"List of API keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization/api-keys/{id}":{"get":{"operationId":"retrieveApiKey","tags":["Administration"],"description":"Retrieve API key detail.","parameters":[{"schema":{"type":"string","description":"API Key ID (key_...)"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"API key detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateApiKey","tags":["Administration"],"description":"Update API key name, scopes, expires_at, or metadata. Metadata uses merge semantics.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","parameters":[{"schema":{"type":"string","description":"API Key ID (key_...)"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"scopes":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":20},"expires_at":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}}},"responses":{"200":{"description":"Updated API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope or escalation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"revokeApiKey","tags":["Administration"],"description":"Soft revoke an API key (sets revoked_at timestamp). Row preserved for audit trail.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","parameters":[{"schema":{"type":"string","description":"API Key ID (key_...)"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["api_key"]},"deleted":{"type":"boolean","enum":[true]},"request_id":{"type":"string"}},"required":["id","object","deleted","request_id"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization/api-keys/{id}/rotate":{"post":{"operationId":"rotateApiKey","tags":["Administration"],"description":"Rotate an API key. Creates a new key with same scopes and rate limit tier. Old key expires in 24 hours.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","parameters":[{"schema":{"type":"string","description":"API Key ID (key_...)"},"required":true,"name":"id","in":"path"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"responses":{"200":{"description":"Rotated API key (includes new raw key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyWithKey"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Key already rotated (in grace period)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization/logs":{"get":{"operationId":"listLogs","tags":["Administration"],"description":"List API request logs for the organization. Filterable by date range, status code, method, and API key. Per-plan access control limits the historical window.","parameters":[{"schema":{"type":"string","description":"Start of date range (ISO 8601). Defaults to 24 hours ago.","example":"2026-04-14T00:00:00Z"},"required":false,"name":"start_date","in":"query"},{"schema":{"type":"string","description":"End of date range (ISO 8601). Defaults to now.","example":"2026-04-15T00:00:00Z"},"required":false,"name":"end_date","in":"query"},{"schema":{"type":"string","description":"Alias for start_date."},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","description":"Alias for end_date."},"required":false,"name":"to","in":"query"},{"schema":{"type":"integer","minimum":100,"maximum":599,"description":"Filter by HTTP status code."},"required":false,"name":"status_code","in":"query"},{"schema":{"type":["boolean","null"],"description":"Filter by outcome: true returns succeeded requests (status < 400), false returns failed requests (status >= 400)."},"required":false,"name":"success","in":"query"},{"schema":{"type":"string","description":"Filter by HTTP method (GET, POST, etc.)."},"required":false,"name":"method","in":"query"},{"schema":{"type":"string","description":"Filter by API key ID (key_...)."},"required":false,"name":"api_key_id","in":"query"},{"schema":{"type":"string","description":"Filter by endpoint type (analytics, class_lookup, class_suggest, compare, compute, fees_estimate, gs_draft, gs_validate, image_search, listing_screening, market_analytics, mcp, monitoring, read, reconcile, reference, rules_lookup, screening, search, utility, write). Historical rows may carry a type the API no longer writes."},"required":false,"name":"endpoint_type","in":"query"},{"schema":{"type":"string","maxLength":200,"description":"Search by path or request ID (case-insensitive substring match)."},"required":false,"name":"search","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Page size (1-100, default 50)"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of request logs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope or plan limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization/logs/{request_id}":{"get":{"operationId":"retrieveLog","tags":["Administration"],"description":"Retrieve a single request log entry by request ID.","parameters":[{"schema":{"type":"string","description":"Request ID (req_...)"},"required":true,"name":"request_id","in":"path"}],"responses":{"200":{"description":"Request log detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogDetail"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope or plan limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/feedback":{"post":{"operationId":"createFeedback","tags":["Feedback"],"description":"Submit structured customer feedback (data issue, bug, feature request, or other).\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).\n\nCredits: 0 per request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["data_issue","bug","feature_request","other"],"description":"Feedback type discriminator.","example":"data_issue"},"message":{"type":"string","minLength":1,"maxLength":5000,"description":"Free-form report body (1–5000 characters)."},"resource_id":{"type":"string","description":"Optional public ID of any referenced entity (tm_/own_/att_/firm_/prc_/…).","example":"tm_550e8400-e29b-41d4-a716-446655440000"},"request_id":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,64}$","description":"Optional request ID of the request where the problem was observed — a request id as issued or accepted by the API (e.g. req_…, or a client-supplied x-request-id). Up to 64 URL-safe characters ([A-Za-z0-9_.-]).","example":"req_01kpjabcdefghijkmnpqrstvwx"},"field":{"type":"string","maxLength":255,"description":"For data issues: which field is wrong (e.g. \"owner.name\")."},"expected_value":{"type":"string","maxLength":5000,"description":"For data issues: what the value should be."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional key-value metadata (max 50 keys)."}},"required":["type","message"],"additionalProperties":false}}}},"responses":{"201":{"description":"Feedback created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}],"x-signa-credits":{"credits":0,"unit":"per_request","action":"feedback","status":"available"}},"get":{"operationId":"listFeedback","tags":["Feedback"],"description":"List feedback submitted by the authenticated organization. Cursor-paginated, newest-first. Filterable by type, status, and created-at range.\n\nCredits: 1 per page.","parameters":[{"schema":{"type":["array","null"],"items":{"type":"string","enum":["data_issue","bug","feature_request","other"]},"maxItems":100,"description":"Filter by feedback type(s). Comma-separated: ?type=data_issue,bug"},"required":false,"name":"type","in":"query","style":"form","explode":false},{"schema":{"type":["array","null"],"items":{"type":"string","enum":["open","acknowledged","resolved"]},"maxItems":100,"description":"Filter by status(es). Comma-separated: ?status=open,acknowledged"},"required":false,"name":"status","in":"query","style":"form","explode":false},{"schema":{"type":"string","description":"Return feedback created at or after this time (YYYY-MM-DD or ISO 8601)."},"required":false,"name":"created_at_gte","in":"query"},{"schema":{"type":"string","description":"Return feedback created strictly before this time (YYYY-MM-DD or ISO 8601)."},"required":false,"name":"created_at_lt","in":"query"},{"schema":{"type":"string","description":"Opaque pagination cursor from the previous page."},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size (1-100, default 20)"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of feedback","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackList"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_page","action":"read","status":"available"}}},"/v1/feedback/{id}":{"get":{"operationId":"retrieveFeedback","tags":["Feedback"],"description":"Retrieve a single feedback item by ID.\n\nCredits: 1 per record.","parameters":[{"schema":{"type":"string","description":"Feedback ID (fbk_...)","example":"fbk_550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Feedback detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"400":{"description":"Invalid feedback ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Feedback not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-signa-credits":{"credits":1,"unit":"per_record","action":"read","status":"available"}}},"/v1/organization/usage/summary":{"get":{"operationId":"getUsageSummary","tags":["Administration"],"description":"Get daily usage breakdown for the authenticated organization. Real time: days the hourly rollup has finalized come from pre-aggregated rollups and days it has not finalized are read live, so a request counts as soon as it completes. Defaults to current billing period when both start_date and end_date are omitted. Monitoring (mark watch, filing watch, marks under management) is a daily meter charged directly to the credit ledger, not a per-request price, so it never appears here — reconcile it against GET /v1/organization/credits.","parameters":[{"schema":{"type":"string","description":"Start of date range (ISO date, e.g. 2026-04-01). Optional — defaults to current billing period start when both start_date and end_date are omitted. Must be provided together with end_date.","example":"2026-04-01"},"required":false,"name":"start_date","in":"query"},{"schema":{"type":"string","description":"End of date range (ISO date, e.g. 2026-04-15). Optional — defaults to current billing period end when both start_date and end_date are omitted. Must be provided together with start_date.","example":"2026-04-15"},"required":false,"name":"end_date","in":"query"},{"schema":{"type":"string","enum":["day","endpoint_type","api_key"],"default":"day","description":"Grouping dimension. Default: day."},"required":false,"name":"group_by","in":"query"},{"schema":{"type":"string","description":"Filter to a specific endpoint type (e.g. search, read)."},"required":false,"name":"endpoint_type","in":"query"}],"responses":{"200":{"description":"Usage summary for the date range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummaryResponse"}}}},"400":{"description":"Validation error (missing or invalid date params)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing billing:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization/usage/estimate":{"get":{"operationId":"getUsageEstimate","tags":["Administration"],"description":"Price the authenticated organization's recorded API traffic at the published credit schedule, broken down by action, with the plan that traffic would land on. Defaults to the last 30 days; the range may not exceed 92 days. `plan_for`, `packs_needed` and `offer` are derived from `credits.per_month`, a 30-day projection of the window, so a window of any length recommends a comparable plan. This is an estimate of past traffic, not a bill or an invoice. Requires the `billing:read` scope; the call itself is not billed.","parameters":[{"schema":{"type":"string","description":"Start of the window (ISO date, e.g. 2026-08-01). Must be provided together with `to`. Omit both for the last 30 days.","example":"2026-08-01"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","description":"End of the window (ISO date, e.g. 2026-08-31), inclusive. Must be provided together with `from` and may not be in the future. Today is accepted; the window then ends at the current moment, which `period.to` reports.","example":"2026-08-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Usage priced at the published credit schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageEstimate"}}}},"400":{"description":"Validation error (bad date format, inverted range, future `to`, range too wide)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing billing:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The aggregate did not finish inside the read pool's statement timeout. Narrow the window and retry — a wide window over a high-volume organization is the usual cause.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization/billing/checkout":{"post":{"operationId":"createBillingCheckout","tags":["Administration"],"description":"Create a Stripe Checkout session for a subscription plan. Internal (dashboard BFF); requires organization:manage.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["starter","growth","scale","enterprise","pro"],"description":"Subscription plan. `pro` is the retired name of `growth`.","example":"starter"},"interval":{"type":"string","enum":["monthly","annual"],"default":"monthly","description":"Billing interval.","example":"monthly"},"success_url":{"type":"string","format":"uri","description":"Redirect on success."},"cancel_url":{"type":"string","format":"uri","description":"Redirect on cancel."},"billing_email":{"type":"string","maxLength":254,"format":"email","description":"Billing email for the Stripe customer (receipts, invoices, failed-payment mail). The dashboard BFF passes the signed-in user's address. Write-once seed: ignored when the organization already has a billing email (later changes flow from the Stripe customer via the customer.updated webhook)."},"offer":{"type":"string","enum":["beta"],"description":"Promotional offer to apply. `beta`: the beta thank-you, 25% off the subscription for 12 months, claimable until the end of 31 October 2026 UTC by beta organizations (on the beta plan, or moved to Free on 1 October) that have not claimed it before. Refused with 400 after the deadline or when the organization is not eligible. Subscriptions only; credit purchases never carry it.","example":"beta"}},"required":["plan"]}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeCheckoutSessionResponse"}}}},"400":{"description":"Validation error; enterprise is not self-serve (`not_self_serve`); the plan has no price on this deployment (`plan_not_available`); the beta offer is closed or the organization is not eligible for it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing organization:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Organization already has an active subscription (type `conflict`); a subscription checkout for the same plan, interval and offer is already open (type `checkout_pending`; resume `checkout_url` — `plan` and `interval` say what it is for — instead of creating a second session; a request without the offer also resumes an open beta-offer checkout for the same plan and interval while the organization is still eligible; any other open checkout is expired and replaced); or a paid subscription is still being set up by the webhooks (type `subscription_pending`; nothing to resume, retry in a minute); or purchases are paused while a payment dispute is open or after it was lost (type `billing_hold`; contact support); or the organization's stored Stripe customer is unknown to this deployment's Stripe account (type `stripe_customer_missing`; nothing is created in its place, contact support)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Billing is not configured on this deployment (Stripe key absent), or another checkout for this organization is in progress and this request could not take the per-organization lock within 2 seconds (`service_unavailable`, retryable — nothing was written); or new sales are paused by the operator (`billing_sales_disabled`, `retryable: false` until sales reopen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}]}},"/v1/organization/billing/checkout-sessions/{sessionId}":{"get":{"operationId":"getBillingCheckoutSession","tags":["Administration"],"description":"Whether a Stripe Checkout session created by this organization has settled, read from Signa's own records rather than Stripe. Internal (dashboard BFF); requires organization:manage. Poll after the checkout redirect until status is no longer open.","parameters":[{"schema":{"type":"string","pattern":"^cs_[A-Za-z0-9_]{1,250}$","description":"Stripe Checkout Session id (cs_...), as substituted into success_url.","example":"cs_test_a1B2c3"},"required":true,"name":"sessionId","in":"path"}],"responses":{"200":{"description":"Checkout session status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeCheckoutSessionStatusResponse"}}}},"400":{"description":"Malformed session id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing organization:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such Checkout session for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Billing is not configured on this deployment (Stripe key absent)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization/billing/portal":{"post":{"operationId":"createBillingPortal","tags":["Administration"],"description":"Create a Stripe billing-portal session (card / invoice / cancel management). Internal (dashboard BFF); requires organization:manage.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"return_url":{"type":"string","format":"uri","description":"Return URL after the portal."},"billing_email":{"type":"string","maxLength":254,"format":"email","description":"Billing email for the Stripe customer (receipts, invoices, failed-payment mail). The dashboard BFF passes the signed-in user's address. Write-once seed: ignored when the organization already has a billing email (later changes flow from the Stripe customer via the customer.updated webhook)."},"flow":{"type":"string","enum":["payment_method_update","subscription_cancel"],"description":"Open a single-purpose portal flow instead of the full portal: update the payment method, or cancel the live subscription. The only portal an organization on a billing hold may open."}}}}}},"responses":{"200":{"description":"Billing portal session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeBillingPortalResponse"}}}},"400":{"description":"Validation error; `subscription_cancel` without a live subscription (`no_live_subscription`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing organization:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The full portal is closed while a payment dispute is open or after it was lost (type `billing_hold`); the `payment_method_update` and `subscription_cancel` flows stay open. Contact support to lift the hold. Or the organization's stored Stripe customer is unknown to this deployment's Stripe account (type `stripe_customer_missing`, every flow; nothing is created in its place, contact support).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Billing is not configured on this deployment (Stripe key absent, `service_unavailable`), or new sales are paused by the operator (`billing_sales_disabled`, `retryable: false`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}]}},"/v1/organization/billing/plan-change":{"post":{"operationId":"changeBillingPlan","tags":["Administration"],"description":"Change the organization's live subscription to another plan or billing interval. Internal (dashboard BFF); requires organization:manage. An upgrade (or a longer interval) is invoiced now with proration and applied only once that invoice is paid — a declined payment leaves the current plan in place and returns the invoice to pay (`pending_payment`). A downgrade (or a shorter interval) is scheduled for the end of the current period (`scheduled`). While a change made here is scheduled, requesting the current plan and interval undoes it (`applied`, nothing is charged), another period-end change replaces it, an upgrade is refused until it is undone, and repeating it answers the same `scheduled`. With `undo_scheduled_change`, the request only ever undoes that change and is refused once it is no longer pending. Organizations without a live subscription subscribe through POST /v1/organization/billing/checkout instead.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["starter","growth","scale","enterprise","pro"],"description":"Target plan. `pro` is the retired name of `growth`.","example":"growth"},"interval":{"type":"string","enum":["monthly","annual"],"default":"monthly","description":"Target billing interval.","example":"monthly"},"undo_scheduled_change":{"type":"boolean","description":"Undo only: `plan` and `interval` name the current plan, and the request may only cancel the change scheduled here (`applied`, nothing charged). If no such change is pending (it already took effect or was cancelled), the request is refused 409 `plan_change_blocked` (`scheduled_change_not_pending`) and nothing is changed or charged. Omitted or false: an ordinary plan change.","example":true}},"required":["plan"]}}}},"responses":{"200":{"description":"Plan change applied, parked pending payment, or scheduled for the period end","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripePlanChangeResponse"}}}},"400":{"description":"Validation error; enterprise is not self-serve (`not_self_serve`); the plan has no price on this deployment (`plan_not_available`); the subscription already bills this plan and interval (`same_plan`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing organization:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The organization has no live subscription to change (type `no_live_subscription`; subscribe through checkout); the subscription cannot take the change (type `plan_change_blocked`, with `reason`: `cancelling` — set to cancel; `scheduled` — the subscription is managed by a schedule Signa did not set up (contact support); `no_period_end`; `not_self_serve` — an enterprise contract; `unresolved_price`; `pending_payment` — a different change is parked awaiting its payment; a repeat of the SAME parked change answers 200 pending_payment with the same invoice; `scheduled_change_pending` — an upgrade (or a longer interval) while a change made here is scheduled: undo it first by requesting the current plan and interval; `scheduled_change_not_pending` — `undo_scheduled_change` was set but no change made here is pending, nothing was changed or charged); or billing changes are paused while a payment dispute is open or after it was lost (type `billing_hold`; contact support); or the organization is suspended for an unpaid subscription invoice (type `billing_suspended`; the plan comes back when the invoice is paid). A past-due organization whose plan is still paid for can change plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Billing is not configured on this deployment (Stripe key absent), or another billing change for this organization is in progress and this request could not take the per-organization lock within 2 seconds, or kept being overtaken by it (`service_unavailable`, retryable — nothing was written); or new sales are paused by the operator (`billing_sales_disabled`, `retryable: false` until sales reopen).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}]}},"/v1/organization/billing/credits/checkout":{"post":{"operationId":"createCreditPackCheckout","tags":["Administration"],"description":"Create a Stripe Checkout session for a one-time prepaid credit purchase of a whole-dollar amount at the organization plan's rate. Internal (dashboard BFF); requires organization:manage. Plans that cannot buy credits (free, beta, enterprise) are refused.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount_usd":{"type":"integer","minimum":10,"maximum":10000,"description":"Whole US dollars to spend, 10 to 10,000 inclusive, tax-exclusive. Credits granted = amount_usd × the organization plan's rate in credits per dollar: Starter 100, Growth 200, Scale 400. Purchased credits expire 12 months after purchase.","example":100},"success_url":{"type":"string","format":"uri","description":"Redirect on success."},"cancel_url":{"type":"string","format":"uri","description":"Redirect on cancel."},"billing_email":{"type":"string","maxLength":254,"format":"email","description":"Billing email for the Stripe customer (receipts, invoices, failed-payment mail). The dashboard BFF passes the signed-in user's address. Write-once seed: ignored when the organization already has a billing email (later changes flow from the Stripe customer via the customer.updated webhook)."}},"required":["amount_usd"]}}}},"responses":{"200":{"description":"Credit purchase checkout session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeCreditPurchaseCheckoutResponse"}}}},"400":{"description":"amount_usd missing, not a whole number of dollars, or outside 10 to 10,000; or the retired sku field was sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope, or plan cannot buy credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Purchases are paused while a payment dispute is open or after it was lost (type `billing_hold`; contact support); or the organization's stored Stripe customer is unknown to this deployment's Stripe account (type `stripe_customer_missing`; nothing is created in its place, contact support)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Billing is not configured on this deployment (Stripe key absent, `service_unavailable`), or new sales are paused by the operator (`billing_sales_disabled`, `retryable: false`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}]}},"/v1/organization/billing/auto-topup":{"get":{"operationId":"getAutoTopUpConfig","tags":["Administration"],"description":"Read the org auto-top-up config. Internal (dashboard BFF); requires organization:manage.","responses":{"200":{"description":"Auto-top-up config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutoTopUpConfigResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing organization:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setAutoTopUpConfig","tags":["Administration"],"description":"Update the org auto-top-up config. Internal (dashboard BFF); requires organization:manage. Any update whose MERGED result would be enabled is refused with 501 — auto-top-up charges saved cards off-session, which Stripe Managed Payments does not support. Disabling (enabled:false) and editing a stored, disabled config remain allowed.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"threshold_credits":{"type":"integer","minimum":0},"refill_to_credits":{"type":["integer","null"],"exclusiveMinimum":0},"refill_sku":{"type":["string","null"],"enum":["pack_5k","pack_25k","pack_100k",null]},"monthly_spend_cap_usd":{"type":"integer","exclusiveMinimum":0},"saved_payment_method":{"type":["string","null"]}}}}}},"responses":{"200":{"description":"Updated auto-top-up config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutoTopUpConfigResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing organization:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"Auto-top-up cannot be enabled: all Signa payments run through Stripe Managed Payments, which does not support automatic off-session charges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization/notification-preferences":{"get":{"operationId":"getNotificationPreferences","tags":["Administration"],"description":"Get the organization's notification preferences. Toggleable categories default to ON. Requires the `organization:manage` scope.","responses":{"200":{"description":"Notification preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferences"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateNotificationPreferences","tags":["Administration"],"description":"Update notification preferences. Merge semantics — only the categories you send are changed. Unknown keys are rejected. Requires the `organization:manage` scope.\n\nThis operation requires an `Idempotency-Key` header (see parameter description for 24h replay and 409-conflict semantics).","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"credit_usage_alerts":{"type":"boolean","description":"Alerts at 90% and 100% of monthly plan credits."},"watch_credit_notifications":{"type":"boolean","description":"Grace-period reminders and watches-resumed notices."},"auto_topup_receipts":{"type":"boolean","description":"Receipts for successful credit top-ups."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Updated notification preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferences"}}}},"400":{"description":"Invalid input (unknown key or non-boolean value)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for safe retries. Responses to a given key are cached for 24h; retrying the same key with the same body replays the original response (with an Idempotent-Replayed: true header); the same key with a different body returns 409 conflict.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[A-Za-z0-9_-]{1,255}$"}}]}},"/v1/organization/credits":{"get":{"operationId":"getCredits","tags":["Administration"],"description":"Get the pooled credit balance for the authenticated organization, a breakdown of remaining credits by grant type (plan vs addon vs promo), the reconciling terms (reserved + pending), and the per-grant expiry schedule in consumption order. The balance reconciles exactly: balance = (plan + addon + promo) − reserved − pending.","responses":{"200":{"description":"Pooled credit balance, grant breakdown, reconciling terms, and expiry schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditBalanceResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Missing billing:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/credits/pricing":{"get":{"operationId":"getCreditPricing","tags":["Administration"],"description":"How many credits each API action costs. No currency amounts; see the pricing page for plans and extra credits.","responses":{"200":{"description":"Credit prices by API action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditPricingResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}