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

# Quickstart

> Make your first API call in under 5 minutes

This guide walks you through two tiers. The first gets you a search result in 5 minutes. The second adds the TypeScript SDK, filters, pagination, and the enriched owner view.

## Tier 1: Your first search (5 minutes)

<Steps>
  <Step title="Get an API key">
    Sign up at [app.signa.so](https://app.signa.so) and create an API key from the dashboard. Your key will look like this:

    ```
    sig_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
    ```

    <Note>
      All keys use the format `sig_{48 hex chars}`. For development or CI, create a separate test organization in the dashboard with its own key so it stays isolated from production usage and billing.
    </Note>
  </Step>

  <Step title="Set your API key as an environment variable">
    <CodeGroup>
      ```bash cURL theme={null}
      export SIGNA_API_KEY="sig_YOUR_KEY"
      ```

      ```typescript TypeScript theme={null}
      // .env
      SIGNA_API_KEY=sig_YOUR_KEY
      ```
    </CodeGroup>
  </Step>

  <Step title="Search for a trademark">
    Pass `q` for the query and comma-separated values for array filters.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -G "https://api.signa.so/v1/trademarks" \
        -H "Authorization: Bearer $SIGNA_API_KEY" \
        --data-urlencode "q=apple" \
        --data-urlencode "offices=uspto"
      ```

      ```typescript TypeScript theme={null}
      const url = new URL("https://api.signa.so/v1/trademarks");
      url.searchParams.set("q", "apple");
      url.searchParams.set("offices", "uspto");

      const response = await fetch(url, {
        headers: { "Authorization": `Bearer ${process.env.SIGNA_API_KEY}` },
      });

      const data = await response.json();
      console.log(data);
      ```
    </CodeGroup>

    <Tip>
      For complex filter combinations or aggregations, use `POST` with a JSON body. See the [Search guide](/guides/search) for details.
    </Tip>
  </Step>

  <Step title="Inspect the response">
    Search endpoints return a list with `data` array, `has_more` for paging, and `request_id` for debugging.

    ```json theme={null}
    {
      "object": "list",
      "data": [
        {
          "id": "tm_a1b2c3",
          "object": "trademark",
          "mark_text": "APPLE",
          "relevance_score": 95,
          "status": {
            "primary": "active",
            "stage": "registered"
          },
          "office_code": "uspto",
          "filing_date": "1977-04-11",
          "classifications": [
            { "nice_class": 9, "goods_services_text": "Computer hardware; integrated circuits; semiconductors" },
            { "nice_class": 42, "goods_services_text": "Computer software design and development services" }
          ],
          "owners": [
            { "id": "own_d4e5f6", "name": "Apple Inc.", "country_code": "US" }
          ]
        }
      ],
      "aggregations": {},
      "has_more": true,
      "pagination": {
        "cursor": "eyJpZCI6ImFiYyJ9"
      },
      "request_id": "req_xyz789"
    }
    ```

    <Tip>
      Switch to `POST` and add `"options": { "aggregations": ["office_code", "status_stage", "nice_classes"] }` to the request body to get faceted counts alongside results. This is useful for building filter UIs. Aggregations are `POST`-only because they don't fit cleanly in a query string.
    </Tip>
  </Step>
</Steps>

***

## Tier 2: SDK, filters, and pagination (15 minutes)

<Steps>
  <Step title="Install the TypeScript SDK">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @signa-so/sdk
      ```

      ```bash pnpm theme={null}
      pnpm add @signa-so/sdk
      ```

      ```bash bun theme={null}
      bun add @signa-so/sdk
      ```
    </CodeGroup>

    Initialize the client:

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

    const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });
    ```
  </Step>

  <Step title="Search with filters">
    Narrow results by office, Nice class, status, filing date, and filing route. By default, `exact` and `fuzzy` strategies run simultaneously. You can restrict or expand strategies with the `strategies` array.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.signa.so/v1/trademarks \
        -H "Authorization: Bearer $SIGNA_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "query": "nova",
          "strategies": ["exact", "phonetic"],
          "filters": {
            "offices": ["uspto", "euipo"],
            "nice_classes": [9, 42],
            "status_stage": ["registered"],
            "filing_date": { "gte": "2020-01-01" }
          },
          "options": { "aggregations": ["office_code", "nice_classes"] },
          "limit": 20
        }'
      ```

      ```typescript TypeScript theme={null}
      const results = await signa.trademarks.search({
        query: "nova",
        strategies: ["exact", "phonetic"],
        filters: {
          offices: ["uspto", "euipo"],
          nice_classes: [9, 42],
          status_stage: ["registered"],
          filing_date: { gte: "2020-01-01" },
        },
        options: { aggregations: ["office_code", "nice_classes"] },
        limit: 20,
      });

      console.log(`Found ${results.data.length} results on this page`);
      console.log("Offices:", results.aggregations?.office_code);
      ```
    </CodeGroup>

    The response includes aggregation counts you can use to build filter UIs:

    ```json theme={null}
    {
      "object": "list",
      "data": [
        {
          "id": "tm_x7y8z9",
          "mark_text": "NOVA",
          "relevance_score": 89,
          "status": { "primary": "active", "stage": "registered" },
          "office_code": "uspto",
          "filing_date": "2021-03-15",
          "classifications": [
            { "nice_class": 9, "goods_services_text": "Downloadable mobile applications for data analytics" }
          ],
          "owners": [
            { "id": "own_x7y8z9", "name": "Nova Technologies LLC", "country_code": "US" }
          ]
        }
      ],
      "aggregations": {
        "office_code": { "uspto": 412, "euipo": 189 },
        "nice_classes": { "9": 347, "42": 254 }
      },
      "has_more": true,
      "pagination": { "cursor": "eyJpZCI6Ing3eSJ9" },
      "request_id": "req_abc123"
    }
    ```

    <Tip>
      Search strategies: `exact` for full-text matches, `phonetic` to catch sound-alikes like "NOVA" / "KNOVA" / "NOWA", `fuzzy` for typo tolerance (fuzziness is always AUTO internally), and `prefix` for starts-with matching. Omit `strategies` to use the default (`exact` and `fuzzy`). For comprehensive clearance searches, use all four: `exact,phonetic,fuzzy,prefix`.
    </Tip>
  </Step>

  <Step title="Handle pagination">
    Results are cursor-based. Pass the `cursor` from one response as a query parameter or body field in the next request.

    <CodeGroup>
      ```bash cURL theme={null}
      # First page
      curl -X POST https://api.signa.so/v1/trademarks \
        -H "Authorization: Bearer $SIGNA_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"query": "nova", "limit": 20}'

      # Next page (use the cursor from the previous response)
      curl -X POST https://api.signa.so/v1/trademarks \
        -H "Authorization: Bearer $SIGNA_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"query": "nova", "limit": 20, "cursor": "eyJpZCI6Ing3eSJ9"}'
      ```

      ```typescript TypeScript theme={null}
      // Automatic pagination with async iterator (list endpoint)
      const marks = await signa.trademarks.list({ offices: 'uspto' });
      for await (const mark of marks) {
        console.log(mark.mark_text, mark.status.stage);
      }

      // Manual page-based pagination (list endpoint)
      let page = await signa.trademarks.list({ offices: 'uspto', limit: 100 });
      const allMarks = [...page.data];

      while (page.has_more) {
        page = await page.getNextPage();
        allMarks.push(...page.data);
      }

      console.log(`Total: ${allMarks.length}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Get full trademark details">
    Retrieve a single trademark by ID to get the full record.

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.signa.so/v1/trademarks/tm_a1b2c3 \
        -H "Authorization: Bearer $SIGNA_API_KEY"
      ```

      ```typescript TypeScript theme={null}
      const mark = await signa.trademarks.retrieve("tm_a1b2c3");

      console.log(mark.mark_text);           // "APPLE"
      console.log(mark.status.stage);        // "registered"
      console.log(mark.owners[0].name);      // "Apple Inc."
      console.log(mark.classifications.map(c => c.nice_class)); // [9, 42]
      console.log(mark.registration_date);   // "1978-10-31"
      ```
    </CodeGroup>

    ```json theme={null}
    {
      "id": "tm_a1b2c3",
      "object": "trademark",
      "mark_text": "APPLE",
      "status": {
        "primary": "active",
        "stage": "registered"
      },
      "office_code": "uspto",
      "filing_date": "1977-04-11",
      "registration_date": "1978-10-31",
      "classifications": [
        {
          "nice_class": 9,
          "nice_edition": "12",
          "goods_services_text": "Computer hardware; integrated circuits; semiconductors",
          "goods_services_language": "en",
          "status": "accepted",
          "class_status_raw": "6"
        },
        {
          "nice_class": 42,
          "nice_edition": "12",
          "goods_services_text": "Computer software design and development services",
          "goods_services_language": "en",
          "status": "accepted",
          "class_status_raw": "6"
        }
      ],
      "owners": [
        { "id": "own_d4e5f6", "name": "Apple Inc.", "country_code": "US", "role": "owner" }
      ],
      "request_id": "req_def456"
    }
    ```

    <Note>
      The detail level varies by endpoint: `GET /v1/trademarks/{id}` returns the full record, list endpoints return a slimmer shape with the fields most useful for result cards, and suggest endpoints return a minimal shape for autocomplete.
    </Note>
  </Step>

  <Step title="Look up an owner">
    Every trademark detail response includes an `owners[]` array. Use the owner ID to get the full owner profile, including entity resolution data and filing statistics.

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.signa.so/v1/owners/own_d4e5f6 \
        -H "Authorization: Bearer $SIGNA_API_KEY"
      ```

      ```typescript TypeScript theme={null}
      const owner = await signa.owners.retrieve("own_d4e5f6");

      console.log(owner.name);                     // "Apple Inc."
      console.log(owner.country_code);             // "US"
      console.log(owner.stats?.trademark_count);    // 1847
      console.log(owner.stats?.registered_count);   // 1203
      console.log(owner.companies?.[0].ticker);      // "AAPL"
      ```
    </CodeGroup>

    ```json theme={null}
    {
      "id": "own_d4e5f6",
      "object": "owner",
      "name": "Apple Inc.",
      "canonical_name": "APPLE INC",
      "name_original_script": null,
      "country_code": "US",
      "entity_type": "corporation",
      "aliases": [
        { "name": "Apple Computer Inc.", "type": "former_name", "source_office": "uspto" }
      ],
      "companies": [
        {
          "source": "sec",
          "source_id": "0000320193",
          "legal_name": "Apple Inc.",
          "ticker": "AAPL",
          "exchange": "NASDAQ",
          "lei": null,
          "entity_status": "active"
        }
      ],
      "stats": {
        "trademark_count": 1847,
        "registered_count": 1203,
        "pending_count": 312,
        "jurisdiction_count": 14,
        "grant_rate": 0.65
      },
      "request_id": "req_ghi789"
    }
    ```
  </Step>
</Steps>

***

## What's next

<Columns cols={2}>
  <Card title="Search guide" icon="magnifying-glass" href="/guides/search">
    Phonetic matching, fuzzy search, aggregations, and filtering strategies for trademark clearance.
  </Card>

  <Card title="Entity resolution" icon="users" href="/guides/entities">
    How Signa normalizes owner names, links corporate parents, and resolves aliases across offices.
  </Card>

  <Card title="Deadline rules" icon="calendar" href="/guides/deadline-rules">
    Jurisdiction-aware renewal and declaration deadlines with rules for 21 jurisdictions.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Complete documentation for all endpoints with interactive playground.
  </Card>
</Columns>