Introduction - Signa Docs

The Signa API is a RESTful JSON API for trademark search, retrieval, and reference data. All endpoints are versioned under /v1/.

Signa is in beta. Response shapes are stable within /v1/, but may still evolve without a major version bump while we finish the initial rollout.

Base URL

https://api.signa.so/v1

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer sig_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys use the format sig_{48 hex chars} and carry one or more scopes (e.g. trademarks:read, portfolios:manage) that control what they can access. Keys are meant for server-to-server use: make calls from your backend, never from client-side code a user can inspect. See Authentication & Keys for creating, rotating, and scoping keys.

Request Format

Content-Type: application/json for request bodies
Query params: snake_case (e.g., ?status_stage=registered)
Arrays: comma-separated values (e.g., ?jurisdictions=US,EU)
Date ranges: flat underscore operators (e.g., ?filing_date_gte=2020-01-01&filing_date_lt=2025-01-01)
Booleans: literal strings true or false (values like 1, yes, or TRUE are rejected)
Dates: ISO 8601 (2026-03-19T12:00:00Z) or date-only (2026-03-19)

Response Format

Single-resource endpoints return the resource at the top level:

{
  "id": "tm_8kLm2nPq",
  "object": "trademark",
  "mark_text": "SIGNA",
  "request_id": "req_abc123"
}

List endpoints wrap results in a standard envelope with has_more at the top level and a pagination object:

{
  "object": "list",
  "data": [...],
  "has_more": true,
  "pagination": {
    "cursor": "eyJ..."
  },
  "request_id": "req_abc123"
}

Every response includes a top-level request_id. Include it when contacting support.

Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad request (validation error)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (insufficient scopes)
`404`	Not found
`409`	Conflict (idempotency key reused with a different body, or already in progress)
`410`	Gone (record merged into another; see Errors)
`422`	Unprocessable (request is well-formed but exceeds a processing limit, e.g. entity too large)
`429`	Rate limited
`500`	Internal server error
`503`	Service unavailable
`504`	Gateway timeout (a bounded server-side computation exceeded its time budget)

Idempotency

Mutating requests (POST, PATCH, DELETE that create or change a resource) require an Idempotency-Key header: any unique string, 1 to 255 characters of letters, numbers, dashes, and underscores.

POST /v1/organization/api-keys
Idempotency-Key: create-prod-key-2026-03-24-001

Same key, same body: the cached response is replayed (safe to retry).
Same key, different body: 409 conflict.
Same key while the original request is still in flight: 409 idempotency_processing; retry shortly.

Keys are scoped to your organization and expire after 24 hours. A handful of read-shaped POST endpoints (search, batch lookup, suggest, watch preview, alert lookup) don’t create anything and are exempt: the header is optional there, though its format is still validated if you send one. See Errors → Idempotency and 409 Conflict for the full exemption list.

Next Steps

Pagination

Cursor-based iteration with stable ordering.

Rate Limits & Quotas

Monthly quota pools, per-minute limits, headers, and 429 handling.

Errors

RFC 9457-inspired error format and catalog.

​Base URL

​Authentication

​Request Format

​Response Format

​Status Codes

​Idempotency

​Next Steps

Pagination

Rate Limits & Quotas

Errors

Base URL

Authentication

Request Format

Response Format

Status Codes

Idempotency

Next Steps