---
document_id: agent.paths.api.quickstart
schema_version: 2
parent_document_id: agent.paths.api
section: querying
---

<!-- Generated by scripts.build_agent_guide; do not edit. -->

# API quickstart / API 快速开始

## Start with published capabilities / 先读取已发布能力

设置 ASKLEAR_BASE_URL 为当前区域 API 地址。匿名读取 GET /v1/public/capabilities?view=reference，查看已正式公开的能力、入口状态和 Docs 链接；目录不授予执行权限，也不产生费用。

Set ASKLEAR_BASE_URL to the regional API base URL. Read GET /v1/public/capabilities?view=reference anonymously to see formally published capabilities, entrypoint status and Docs links; the directory grants no execution access and is free.

```sh
curl --fail-with-body "$ASKLEAR_BASE_URL/v1/public/capabilities?view=reference" \ -H "Accept: application/json"
```

## Choose an entrypoint and prepare authentication / 选择入口并准备鉴权

只选择返回 status=available 的 HTTP 入口，并打开它的 Docs 链接读取 method、path、输入、计费和幂等规则。公开目录不代表当前账号有权限；需要鉴权的接口再设置 ASKLEAR_API_KEY。

Choose an HTTP entrypoint whose status is available and open its Docs link for the method, path, inputs, billing and idempotency rules. A public listing does not grant account access; set ASKLEAR_API_KEY only for endpoints that require authentication.

## Read the directory response / 看懂目录返回

下面是删减的合成目录响应，仅展示结构，不是当前区域的实时能力快照。以响应中的 catalog_version、region、status 和 entrypoint contract 为准。

The abbreviated synthetic directory response below illustrates structure, not the current regional snapshot. Use catalog_version, region, status and each entrypoint contract from the response.

```json
{
  "schema_version": 1,
  "region": "cn",
  "catalog_version": "published-catalog",
  "stale": false,
  "platforms": [{
    "id": "published-platform",
    "capabilities": [{
      "id": "native-http:published.operation",
      "entrypoints": [{
        "type": "http",
        "status": "available",
        "method": "POST",
        "path": "/v1/published/operation",
        "docs_href": "https://docs.asklear.cn/capabilities/native-http%3Apublished.operation"
      }]
    }]
  }]
}
```

## Check scope, access and charges / 检查范围、权限与费用

按选定入口的实际 method/path/schema 构造请求。付费请求遵循该入口的 upper_bound、批准、幂等和错误恢复合同；合成目录中的占位值不代表价格或可执行权限。

Build the request from the selected entrypoint’s method, path and schema. For paid calls, follow its upper bound, approval, idempotency and recovery contract; placeholder values in the synthetic directory are not price or access promises.

发生错误时保留 code、request_id 或 task_ref，按[错误处理](https://docs.asklear.cn/api/errors)修正。超时或结果未知先读取原任务或结果，不立即更换幂等键重跑。

On errors, preserve the code, request_id or task_ref and follow [error guidance](https://docs.asklear.cn/en/api/errors). For timeouts or unknown outcomes, read the original task or result instead of immediately retrying with a new idempotency key.

## Continue your data task / 继续你的数据任务

需要查看完整字段时打开[API 参考](https://docs.asklear.cn/api/reference)，再按入口的真实契约调用；不要把一个能力的字段、枚举或分页参数复制到另一个能力。

Open the [API reference](https://docs.asklear.cn/en/api/reference) for complete fields, then call the endpoint using its actual contract; do not copy fields, enums or pagination inputs between capabilities.

只想排查凭据时，可按[鉴权说明](https://docs.asklear.cn/api/authentication)检查 API Key 或程序 OAuth；它不替代能力目录和具体接口合同。

For credential troubleshooting, use [authentication guidance](https://docs.asklear.cn/en/api/authentication) to check an API key or programmatic OAuth; it does not replace the capability directory or endpoint contract.
