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

# Introduction

> Base URL, authentication, request and response format

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

<Note>
  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.
</Note>

## Base URL

```
https://api.signa.so/v1
```

## Authentication

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

```bash theme={null}
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](/guides/authentication) 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/api-reference/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](/api-reference/errors#idempotency-and-409-conflict) for the full exemption list.

## Next Steps

<Columns cols={3}>
  <Card title="Pagination" icon="layer-group" href="/api-reference/pagination">
    Cursor-based iteration with stable ordering.
  </Card>

  <Card title="Rate Limits & Quotas" icon="gauge" href="/api-reference/rate-limits">
    Monthly quota pools, per-minute limits, headers, and 429 handling.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    RFC 9457-inspired error format and catalog.
  </Card>
</Columns>