API フィールド
名前、型、必須マーカーを付けてリクエストパラメータとレスポンスフィールドを記述します。子フィールドをネストし、リクエストとレスポンスの例を表示できます。
2026年11月19日更新
API フィールドは、エンドポイントが受け取るパラメータと返すフィールドを一覧にします。各項目には名前、型、required などのマーカーが表示され、その下に説明が付きます。どのページにも手で記述できます。仕様ファイルから生成する完全なリファレンスについては、OpenAPI を参照してください。
idpathstringrequired取得するユーザーの ID。
expandquerystring[]default: []レスポンスに含める関連オブジェクト。例: team。
<ParamField path="id" type="string" required>
The ID of the user to fetch.
</ParamField>
<ParamField query="expand" type="string[]" default="[]">
Related objects to include in the response, such as `team`.
</ParamField>
パラメータ
<ParamField> は、リクエストで送信する項目を記述します。送信先を示すプロップで名前を指定します: path、query、body、header のいずれかです。その場所は名前の横に表示されます。
AuthorizationheaderstringrequiredBearer に続けて API キーを指定します。
emailbodystringrequired新しいユーザーのメールアドレス。
nicknamebodystringdeprecated代わりに display_name を使用してください。
<ParamField header="Authorization" type="string" required>
`Bearer` followed by your API key.
</ParamField>
<ParamField body="email" type="string" required>
The new user's email address.
</ParamField>
<ParamField body="nickname" type="string" deprecated>
Use `display_name` instead.
</ParamField>
レスポンスフィールド
<ResponseField> は、レスポンスが返す項目を記述します。名前は name で指定します。
idstringrequiredユーザーの一意な ID。
created_atstringユーザーが作成された日時 (ISO 8601 形式のタイムスタンプ)。
<ResponseField name="id" type="string" required>
Unique ID for the user.
</ResponseField>
<ResponseField name="created_at" type="string">
When the user was created, as an ISO 8601 timestamp.
</ResponseField>
ネストしたフィールド
親フィールドの内側で、子フィールドを <Expandable> で囲みます。読者は Show をクリックして表示するため、長いオブジェクトがページを占有しません。
teamobjectユーザーが所属するチーム。
Show properties
team.idstringチームの一意な ID。
team.namestringチームの表示名。
<ResponseField name="team" type="object">
The team the user belongs to.
<Expandable title="properties">
<ResponseField name="team.id" type="string">
Unique ID for the team.
</ResponseField>
<ResponseField name="team.name" type="string">
The team's display name.
</ResponseField>
</Expandable>
</ResponseField>
トグルには「Show」に続けて title が表示されます。つまり title="properties" では Show properties になります。title を省略すると Show details と表示されます。
リクエストとレスポンスの例
<RequestExample> と <ResponseExample> は、内部のコードブロックを コードグループ に変換し、ブロックごとにタブを 1 つ作成します。ページ上では記述した位置に表示されます。
curl https://api.acme.com/v1/users/usr_123 \
-H "Authorization: Bearer sk_live_abc123"{ "id": "usr_123", "email": "[email protected]" }<RequestExample>
```bash cURL
curl https://api.acme.com/v1/users/usr_123 \
-H "Authorization: Bearer sk_live_abc123"
```
```javascript Node.js
const user = await acme.users.retrieve("usr_123");
```
</RequestExample>
<ResponseExample>
```json 200
{ "id": "usr_123", "email": "[email protected]" }
```
```json 404
{ "error": "not_found" }
```
</ResponseExample>
エンドポイント行
<API> は 1 つのエンドポイントを、メソッドとパスを 1 行にまとめて表示します。サイトに同じメソッドとパスのページがある場合、その行はそのページへリンクします。リンク先は、エンドポイント用に作成したページ、またはそれがない場合は OpenAPI リファレンス が生成したページです。
/users/{id}
<API method="GET" path="/users/{id}" />
ガイドで、ステップが呼び出すエンドポイントを読者に示すときに使用します。パスは仕様ファイルのとおりに、波かっこ内のパラメータを含めて記述してください。
プロップ
API
| Prop | Type | Default | Description |
|---|---|---|---|
method | string | GET | HTTP メソッド。GET や POST など。 |
path | string | none | エンドポイントのパス。例: /users/{id}。 |
ParamField と ResponseField
| Prop | Type | Default | Description |
|---|---|---|---|
path, query, body, header | string | none | ParamField のみ。項目の名前。使用するプロップによって場所のラベルが決まります。 |
name | string | none | 項目の名前。ResponseField で使用するか、場所を指定しない ParamField で使用します。 |
type | string | none | 名前の横に表示される型。例: string や object。 |
required | boolean | false | required マーカーを表示します。 |
deprecated | boolean | false | deprecated マーカーを表示します。 |
default | string | none | 値とともに default: を表示します。 |
タグの間の内容が、その項目の説明になります。
Expandable
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | none | トグルのラベルを補完します: Show + title。 |
defaultOpen | boolean | false | 展開された状態で開始します。 |
<RequestExample> と <ResponseExample> はプロップを受け取りません。各コードブロックには、コードグループ内と同じようにラベルを付けてください。
ビジュアルエディターでの表示
これらのコンポーネントは、ビジュアルエディターでは読み取り専用のソースとして表示され、変更せずに保存されます。編集はソースモードで行ってください。<API> は、移動または削除できるエンドポイントブロックとして表示されます。