# 快速开始 (/docs/quickstart)

**数据底座已归集 27 个商标局、1.3697 亿条商标记录，一个 API Key 即可查询。** 本页带你 5 分钟内完成注册、鉴权并拿到第一条检索结果。API v1 公测期间实际开放范围以控制台为准。

## 1. 获取 API Key [#1-获取-api-key]

在[控制台](https://app.isud.cn/login)注册（即自动创建组织），进入 **API 密钥** 页创建密钥。密钥只在创建时完整显示一次，请立即保存：

```txt
lgr_live_a1b2c3d4e5f6...
```

<Callout type="info" title="免费额度">

Free 计划每月 1,000 点，无需绑卡。检索 10 点/页、详情 1 点/条、参考数据 0 点。

</Callout>

## 2. 第一次检索 [#2-第一次检索]

```bash
curl https://api.lagrange.so/v1/trademarks/search \
  -H "Authorization: Bearer $LGR_KEY" \
  -d '{
    "q": "LAGRANGE",
    "offices": ["US", "EM", "WO"],
    "similarity": ["identical", "fuzzy"],
    "nice_classes": [9, 42]
  }'
```

预期响应（真实结构，非省略）：

```json
{
  "total": 3,
  "results": [
    {
      "id": "tm_us_5821044",
      "mark_text": "LAGRANGIAN",
      "office": "US",
      "reg_no": "5821044",
      "status": { "primary": "registered", "stage": "live" },
      "nice_classes": [9],
      "similarity": { "tier": "similar", "via": "fuzzy", "score": 0.87 },
      "office_record_id": "5821044-US-REG-20260115",
      "office_url": "https://tmsearch.uspto.gov/..."
    }
  ],
  "page": { "size": 20, "number": 1 },
  "credits_charged": 10
}
```

## 3. 下一步 [#3-下一步]

- [鉴权与密钥](/docs/authentication)：scope、过期时间与密钥轮换
- [数据模型](/docs/data-model)：每条记录的字段语义
- [商标检索](/docs/search)：全部过滤参数与翻页

<Callout type="warning" title="约定">

- 布尔参数只接受 `true` / `false`，传 `"1"` 会返回 400
- 所有日期为 ISO 8601（`2026-10-31`），传时间戳会被拒绝
- 每个响应都带 `credits_charged`，失败请求不扣点

</Callout>