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

> ## Agent Instructions
> このマニュアルの URL を人間の読者に案内・リンクするときは、末尾の .md を外した URL (例: https://docs.stockwork.ai/guide/data-model) を使ってください。.md 付きの URL は AI 向けの Markdown 版で、ブラウザでは整形されずに表示されます。
> When linking to this manual for a human reader, use the page URL without the trailing .md (e.g. https://docs.stockwork.ai/guide/data-model). URLs ending in .md serve raw Markdown intended for AI tools.

# 予定を一覧取得

> 組織内のユーザーが連携しているカレンダーの予定を返す。カーソルページネーション
(`updated_at` 順)。開始時刻順が必要な場合は取得側で並べ替える。

取り込まれるのは、Stockwork ユーザーとしてカレンダーを連携している人の予定だけ。
そのうち返すのは、**会議 URL があり、カレンダーで非公開に設定されていない予定**のみ
(面談・私用などの予定や非公開の予定は返さない。「API キーの見える範囲」を参照)。
カレンダーでの作成・変更が反映されるまで通常数分かかる(保証はない)。
同期対象は過去 7 日から 60 日先まで。

ユーザーがカレンダー連携を解除すると、その人の予定は削除され、差分同期では
検知できない。連携状況は `GET /v1/calendar-connections/` で確認する。




## OpenAPI

````yaml /openapi/v1.yaml get /v1/calendar-events/
openapi: 3.0.3
info:
  title: Stockwork Public API
  version: 1.1.0
  description: >
    Stockwork の取引(Deal)・会社(Account)・コンタクト(Contact)・商談ログ(Meeting Log)・

    コンタクト活動(Contact Activity)を外部システムから操作し、商談音声(Meeting Record:

    録音・録画と文字起こし)の読み取りと、カレンダー予定への録画予約を行う公開 API。


    ## 認証

    `Authorization: Bearer sk_<base62>` 形式の API キーを送る。

    キーは Stockwork 管理画面で発行し、発行時のみ平文が 1 回だけ返却される(以降は再表示不可)。

    発行できるのは組織の管理者のみ。


    ### API キーの見える範囲

    API キーは**組織単位の資格情報**で、特定のユーザーには紐づかない(発行者が退職しても使える)。

    組織内のデータを対象とするが、**ユーザーが非公開に設定したものは返さない**。


    | データ | API キーで返る範囲 |

    |---|---|

    | 取引・会社・コンタクト・商談ログ・コンタクト活動 | 組織内すべて |

    | カレンダー予定 | 会議 URL があり、カレンダーで非公開に設定されていない予定 |

    | 商談音声 | 組織内公開(`visibility: public`)のものと、そのキーで取り込んだもの |


    カレンダーの非公開は、Outlook の秘密度 `private` / `personal` / `confidential`、

    Google の公開設定 `private` / `confidential` を指す。


    ## 識別子

    Stockwork が発行する `id`(record_id、18 文字)が**全レコードの唯一の identity**。

    クライアントはこの `id` を保存し、以降の取得・更新に使用する。


    レコード間の参照もすべて record_id で行う。`properties.account_id`(Contact → Account)、

    `properties.deal_id`(Meeting Log → Deal)、`properties.contact_id`(Contact
    Activity →

    Contact)、`properties.owner_id`(Deal → User)。担当ユーザーの氏名・メールアドレスは

    `GET /v1/users/` で解決する。


    メールアドレスから担当者の record_id を引きたい場合は `GET /v1/users/?email=...` を使う。

    ただしこれは**発見用のフィルタであって識別子ではない**。メールアドレスは変更され得るため、

    解決した record_id を保存して以降の参照に使うこと(HubSpot / Salesforce と同じ作法)。


    ## エラー

    全てのエラーは次の封筒で返る。`error.code` は機械可読な enum、`error.message` は人間向けの

    説明文(日本語)。バリデーション失敗時のみ `error.fields` にフィールド単位の詳細が入る。


    ```json

    {
      "error": {
        "code": "validation_error",
        "message": "リクエストの検証に失敗しました。",
        "fields": [
          {"name": "properties.name", "code": "required", "message": "この項目は必須です。"}
        ]
      }
    }

    ```


    ## ロール

    API キー発行時に付与する **role** で操作範囲を制限する。Stockwork 既存の組織ロールと

    同じ概念を流用(リソース単位の細かいスコープ分割は提供しない):

    - `read` — 読み取りのみ

    - `analyst` — 読み取り + 分析(本 API では read 相当)

    - `write` — 読み取り + 書き込み

    - `admin` — 全権限


    ### エンドポイントと必要 role の対応

    | メソッド + パス | 必要 role |

    |---|---|

    | `GET /v1/deals/` / `/v1/deals/{record_id}/` / `/v1/deals/properties/` |
    `read` |

    | `POST /v1/deals/search/` | `read` |

    | `POST /v1/deals/` / `PATCH /v1/deals/{record_id}/` | `write` |

    | `GET /v1/companies/` / `/v1/companies/{record_id}/` /
    `/v1/companies/properties/` | `read` |

    | `POST /v1/companies/search/` | `read` |

    | `POST /v1/companies/` / `PATCH /v1/companies/{record_id}/` | `write` |

    | `GET /v1/contacts/` / `/v1/contacts/{record_id}/` /
    `/v1/contacts/properties/` | `read` |

    | `POST /v1/contacts/search/` | `read` |

    | `POST /v1/contacts/` / `PATCH /v1/contacts/{record_id}/` | `write` |

    | `GET /v1/meeting-logs/` / `/v1/meeting-logs/{record_id}/` /
    `/v1/meeting-logs/properties/` | `read` |

    | `POST /v1/meeting-logs/search/` | `read` |

    | `POST /v1/meeting-logs/` / `PATCH /v1/meeting-logs/{record_id}/` | `write`
    |

    | `GET /v1/contact-activities/` / `/v1/contact-activities/{record_id}/` /
    `/v1/contact-activities/properties/` | `read` |

    | `POST /v1/contact-activities/search/` | `read` |

    | `POST /v1/contact-activities/` / `PATCH
    /v1/contact-activities/{record_id}/` | `write` |

    | `GET /v1/meeting-records/` / `/v1/meeting-records/{record_id}/` /
    `/v1/meeting-records/properties/` | `read` |

    | `POST /v1/meeting-records/search/` | `read` |

    | `GET /v1/calendar-events/` / `/v1/calendar-events/{record_id}/` | `read` |

    | `POST` / `DELETE /v1/calendar-events/{record_id}/recording/` | `write` |

    | `PATCH /v1/calendar-events/{record_id}/deal-linking/` | `write` |

    | `GET /v1/calendar-connections/` | `read` |

    | `GET /v1/users/` / `/v1/users/{record_id}/` | `read` |


    上位 role は下位 role を内包する(`write` キーは `read` 操作も可)。

    商談音声(`/v1/meeting-records/`)とユーザーは読み取り専用で、作成・更新のエンドポイントは無い。

    録画の予約は会議の参加者から見える操作である。`write` キーの発行先に注意すること。


    ## カレンダー予定からの録画


    連携カレンダーの予定に録画 Bot を予約し、録音後に紐付ける取引を事前に設定できる。

    画面の「予約録画」「取引自動紐づけ」と同じ処理を通る。


    - 予約: `POST /v1/calendar-events/{record_id}/recording/`(本文の `deal_linking`
    で取引の事前設定も同時に行える)

    - 取引を事前指定した録音は、文字起こし完了時に自動でその取引に登録され、商談ログが作成される

    - 録音の状態は予定の `recording`、または `GET /v1/meeting-records/{record_id}/` の
    `status` で確認する
      (`reserved` → `processing` → `available` → `registered`)

    ### 録音の所有者


    録音には必ず所有者(Stockwork ユーザー)がいる。カレンダー予約では**予定の持ち主**

    (`CalendarEvent.owner_id`)が所有者になり、録音の閲覧権限・文字起こし利用枠の計上先・

    登録後の商談ログの作成者になる。


    ### 再送と重複


    汎用の冪等性キーは提供しない。代わりに各操作を再送しても結果が変わらないようにしている。

    録画の予約・取り消しは、再送しても `200` で現在の状態を返す(二重予約にならない)。


    ### 会議の時刻変更・キャンセル


    予約した録音は、カレンダー側の時刻変更・URL 変更・キャンセルに自動で追従する

    (API から再予約する必要はない)。反映はカレンダーの同期と同じく通常数分。


    ## 検索(プロパティ値による絞り込み)

    GUI 一覧画面と同等の表現力でレコードを検索できる `POST /v1/<resource>/search/`

    を提供する。クエリ文字列ではなく POST body にフィルタを含めるため、WAF / 中間機器の

    URL 長制限の影響を受けない。


    - **2 階層構造**: グループ間 OR / グループ内 AND(GUI と同じ。最大 10 グループ)

    - **対象フィールド**: コアフィールド(`name` / `amount` / `stage` 等)+ カスタム
      プロパティ(`PropertyDefinition.api_name` で指定)
    - **operator**: text / number / date / select / boolean のそれぞれに必要な集合を提供
      (詳細は `FilterOperator` schema)
    - **select 値の解決**: ラベルではなく**内部値の完全一致**のみ(fuzzy match なし)

    - **`is_null` / `is_empty` の意味論**: 該当プロパティの値レコードが存在しない場合も
      含める(GUI と同じ)
    - **ページネーション**: 検索はページ番号型(`page` / `page_size`)。任意の複合ソート
      (`sort_by` / `sort_order`)を許すため、カーソル型とは両立しない。
      `page * page_size` は **10,000 を超えられない**(超過時は `400`)。
      全件走査には `GET /v1/<resource>/?updated_after=...` のカーソルページネーションを使う。

    ## `updated_at` と差分取得


    `updated_at` は**レコードの値が最後に変わった日時**で、行への書き込み日時ではない。

    コアフィールド・カスタムプロパティ・アクティビティ件数などの集計値のいずれかが実際に

    変わったときに進む。商談ログやメールを記録した場合も、それが集計値を動かすため進む。


    同じ値での再保存（SFA 同期が同一値を書き戻した場合を含む）、他レコードとの紐付け変更、

    日次バッチが再計算する予測値（受注確率・ヘルススコア）では進まない。


    `updated_after` を差分同期のウォーターマークに使う場合、活動の記録でも親レコードが

    再取得対象になる点に注意する。


    ## レート制限

    - API キー単位: `1000 / 分`

    - 組織合算: `5000 / 分`


    全レスポンス(成功・失敗を問わず)に次のヘッダを付与する。クライアントは残量を見て

    事前に減速できる。


    - `X-RateLimit-Limit` — 現在の窓の上限回数(API キー単位)

    - `X-RateLimit-Remaining` — 現在の窓の残り回数

    - `X-RateLimit-Reset` — 窓がリセットされる Unix 時刻(秒)


    超過時は `429 Too Many Requests` + `Retry-After` ヘッダ。


    ## 変更履歴


    ### 1.1.0


    - 追加: 商談音声(`/v1/meeting-records/`)の読み取り(一覧・検索・プロパティ・詳細)

    - 追加: カレンダー予定(`/v1/calendar-events/`)と録画の予約・取り消し・取引の事前設定

    - 追加: カレンダー連携状況(`/v1/calendar-connections/`)

    - 追加: エラーコード `quota_exceeded` / `invalid_state` と `error.reason`

    - 追加: プロパティ値・プロパティ定義の型 `multi_select`(文字列の配列)

    - 明記: API キーの見える範囲(非公開の予定・商談音声は返さない)

    - 既存のエンドポイントの応答・エラー形式に変更はない
  contact:
    name: Stockwork Public API Support
servers:
  - url: https://api.strixai.jp
    description: Production
  - url: https://api-dev.strixai.jp
    description: Development(検証環境)
security:
  - BearerApiKey: []
tags:
  - name: Deals
    description: 取引リソース
  - name: Companies
    description: 会社(Account)リソース
  - name: Contacts
    description: コンタクトリソース
  - name: Meeting Logs
    description: 商談ログ(Deal 配下の活動)リソース
  - name: Contact Activities
    description: コンタクト活動(Contact 配下の活動)リソース
  - name: Meeting Records
    description: 商談音声(録音・録画とその文字起こし)リソース。read-only
  - name: Users
    description: Stockwork ユーザー(担当者)リソース。read-only
  - name: Calendar Events
    description: |
      カレンダー予定リソース。組織内のユーザーが連携しているカレンダー(Outlook / Google)の
      予定を読み取り、録画 Bot の予約・取り消しと、録音後に紐付ける取引の事前設定を行う。
      予定そのものの作成・更新・削除は提供しない(カレンダー側で行う)。
  - name: Calendar Connections
    description: カレンダー連携状況リソース。read-only(接続・解除は Stockwork の画面で行う)
paths:
  /v1/calendar-events/:
    get:
      tags:
        - Calendar Events
      summary: 予定を一覧取得
      description: |
        組織内のユーザーが連携しているカレンダーの予定を返す。カーソルページネーション
        (`updated_at` 順)。開始時刻順が必要な場合は取得側で並べ替える。

        取り込まれるのは、Stockwork ユーザーとしてカレンダーを連携している人の予定だけ。
        そのうち返すのは、**会議 URL があり、カレンダーで非公開に設定されていない予定**のみ
        (面談・私用などの予定や非公開の予定は返さない。「API キーの見える範囲」を参照)。
        カレンダーでの作成・変更が反映されるまで通常数分かかる(保証はない)。
        同期対象は過去 7 日から 60 日先まで。

        ユーザーがカレンダー連携を解除すると、その人の予定は削除され、差分同期では
        検知できない。連携状況は `GET /v1/calendar-connections/` で確認する。
      parameters:
        - $ref: '#/components/parameters/StartAfter'
        - $ref: '#/components/parameters/StartBefore'
        - $ref: '#/components/parameters/OwnerId'
        - $ref: '#/components/parameters/MeetingKey'
        - $ref: '#/components/parameters/IncludeCancelled'
        - $ref: '#/components/parameters/UpdatedAfter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: 一覧取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarEventListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - BearerApiKey: []
components:
  parameters:
    StartAfter:
      name: start_after
      in: query
      schema:
        type: string
        format: date-time
      description: 開始時刻がこの日時以降(`start_time >= 値`)の予定のみを返す
    StartBefore:
      name: start_before
      in: query
      schema:
        type: string
        format: date-time
      description: 開始時刻がこの日時より前(`start_time < 値`)の予定のみを返す
    OwnerId:
      name: owner_id
      in: query
      schema:
        type: string
        pattern: ^[A-Za-z0-9]{18}$
      description: 予定の持ち主(ユーザーの record_id)で絞り込む
    MeetingKey:
      name: meeting_key
      in: query
      schema:
        type: string
      description: |
        同じ会議の予定だけを返す。値は `CalendarEvent.meeting_key` をそのまま渡す
    IncludeCancelled:
      name: include_cancelled
      in: query
      schema:
        type: boolean
        default: false
      description: |
        `true` のとき、キャンセルされた予定(`status: cancelled`)も返す。
        `updated_after` による差分同期ではキャンセルを取りこぼさないよう `true` を推奨する
    UpdatedAfter:
      name: updated_after
      in: query
      schema:
        type: string
        format: date-time
      description: 指定日時以降に更新されたレコードのみを返す
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 100
      description: 1 ページあたりの最大件数
    Cursor:
      name: after
      in: query
      schema:
        type: string
      description: 次ページ取得用カーソル。前回レスポンスの `paging.next.after` をそのまま渡す
  schemas:
    CalendarEventListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CalendarEvent'
        paging:
          $ref: '#/components/schemas/Paging'
      required:
        - results
        - paging
    CalendarEvent:
      type: object
      description: |
        連携カレンダーの予定 1 件。予定は持ち主ごとに別レコードになるため、同じ会議に
        Stockwork ユーザーが複数参加していると、同じ会議が複数の予定として現れる。
        同じ会議かどうかは `meeting_key` で判別する。

        API キーに返るのは会議 URL があり、非公開でない予定だけ。予定が後から非公開に
        変更された場合は、一覧から消え、単体取得も `404` になる(差分同期では検知できないため、
        保持している予定を取得して `404` なら対象外になったと扱う)。
      properties:
        id:
          type: string
          description: Stockwork record_id(18 文字)
          example: Ce7XkQpYz3Lh9vMs2N
        title:
          type: string
          description: 予定の件名
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - active
            - cancelled
          description: '`cancelled` はカレンダー側でキャンセル(削除)された予定'
        meeting_url:
          type: string
          nullable: true
          description: Web 会議の参加 URL。無い予定は録画を予約できない
        meeting_platform:
          type: string
          nullable: true
          enum:
            - zoom
            - google_meet
            - microsoft_teams
            - other
            - null
        meeting_key:
          type: string
          nullable: true
          description: |
            同じ会議を束ねる不透明なキー。会議 URL と開始時刻から計算され、どちらかが
            変わると値も変わる。`meeting_url` が無い予定は `null`
        owner_id:
          type: string
          description: |
            予定の持ち主(カレンダーを連携しているユーザー)の record_id。
            録画を予約すると、この人が録音の所有者(閲覧権限・文字起こし利用枠の計上先)になる
        organizer_email:
          type: string
          nullable: true
          description: 会議の主催者のメールアドレス
        ical_uid:
          type: string
          nullable: true
          description: カレンダー側の予定識別子(iCalUId)。繰り返し予定では各回で共通
        is_recurring:
          type: boolean
          description: 繰り返し予定の 1 回か
        recording:
          $ref: '#/components/schemas/CalendarEventRecording'
        deal_linking:
          $ref: '#/components/schemas/DealLinking'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          description: |
            予定の内容・録画の予約/取り消し・取引の事前設定のいずれかが変わった日時。
            内容が同じままの再同期では進まない。録画の進行(入室・終了)は予約先の商談音声
            (`recording.meeting_record_id`)の `updated_at` で追う
      required:
        - id
        - title
        - start_time
        - end_time
        - status
        - meeting_url
        - meeting_platform
        - meeting_key
        - owner_id
        - organizer_email
        - ical_uid
        - is_recurring
        - recording
        - deal_linking
        - created_at
        - updated_at
      example:
        id: Ce7XkQpYz3Lh9vMs2N
        title: 株式会社サンプル 定例
        start_time: '2026-10-03T00:30:00Z'
        end_time: '2026-10-03T01:30:00Z'
        status: active
        meeting_url: https://teams.microsoft.com/l/meetup-join/19%3ameeting_sample
        meeting_platform: microsoft_teams
        meeting_key: mk_5c1f0d8e2a7b4c9d8e7f6a5b4c3d2e1f
        owner_id: Us7XkQpYz3Lh9vMs2N
        organizer_email: yamada@example.co.jp
        ical_uid: 040000008200E00074C5B7101A82E0080000000000000000000000000000000
        is_recurring: false
        recording:
          state: scheduled
          scheduled_by: manual
          meeting_record_id: Mr7XkQpYz3Lh9vMs2N
          is_representative: true
        deal_linking:
          deal_id: Rb7XkQpYz3Lh9vMs2N
          genre: 初回商談
          assignee_ids:
            - Ub3MqTzW5Ly8Nc1KsP
          participants: 先方 佐藤様
        created_at: '2026-09-28T02:00:00Z'
        updated_at: '2026-09-28T02:05:00Z'
    Paging:
      type: object
      description: ページネーション情報
      properties:
        next:
          type: object
          nullable: true
          description: 次ページが無いときは null
          properties:
            after:
              type: string
              description: 次ページ取得用カーソル
            link:
              type: string
              format: uri
              description: 次ページの完全 URL
          required:
            - after
            - link
    Error:
      type: object
      description: |
        全エラーレスポンスの共通封筒。
      properties:
        error:
          type: object
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: 人間向けの説明文(日本語)
            fields:
              type: array
              description: |
                `code` が `validation_error` のときのみ存在。フィールド単位の詳細。
              items:
                $ref: '#/components/schemas/FieldError'
            reason:
              allOf:
                - $ref: '#/components/schemas/InvalidStateReason'
              description: '`code` が `invalid_state` のときのみ存在。状態エラーの理由(1.1.0 で追加)。'
          required:
            - code
            - message
      required:
        - error
      example:
        error:
          code: validation_error
          message: リクエストの検証に失敗しました。
          fields:
            - name: properties.name
              code: required
              message: この項目は必須です。
    CalendarEventRecording:
      type: object
      description: 予定に対する録画の状態
      properties:
        state:
          type: string
          enum:
            - none
            - scheduled
            - recording
            - recorded
            - failed
          description: |
            - `none` — 予約なし
            - `scheduled` — 録画 Bot を予約済み(会議開始前)
            - `recording` — Bot が会議に入室し録画中
            - `recorded` — 録画が終了した
            - `failed` — 入室・録画に失敗した(開始 5 分後も入室していない場合を含む)
        scheduled_by:
          type: string
          nullable: true
          enum:
            - manual
            - keyword
            - null
          description: |
            予約の経緯。`manual` は画面または API による予約、`keyword` は連携設定の
            キーワード自動予約。予約なしは `null`
        meeting_record_id:
          type: string
          nullable: true
          description: >
            録音(商談音声)の record_id。`GET /v1/meeting-records/{record_id}/`
            で状態・文字起こしを取得できる。

            **会議開始前は、予定の時刻や URL が変わると別の id に置き換わることがある。**

            開始前は予定を起点に参照し、この値を長期保存しないこと
        is_representative:
          type: boolean
          description: |
            同じ会議(`meeting_key` が同じ予定)を複数人が予約している場合、録音の設定が
            効く代表の予定かどうか。API の `deal-linking` は同じ会議の全予定に書き込むため、
            通常は意識しなくてよい
      required:
        - state
        - scheduled_by
        - meeting_record_id
        - is_representative
    DealLinking:
      type: object
      description: |
        録音後に紐付ける取引の事前設定。画面の「取引自動紐づけ」と同じ。
        文字起こし完了後、`deal_id` の取引へ自動で確定紐付けされ、商談ログが作成される。
      properties:
        deal_id:
          type: string
          nullable: true
          description: 紐付ける取引の record_id
        genre:
          type: string
          nullable: true
          description: >
            商談ジャンル。選択肢は `GET /v1/meeting-records/properties/` の `genre` の
            `options`
        assignee_ids:
          type: array
          items:
            type: string
          description: |
            担当者(User)の record_id の配列。`GET /v1/users/` で解決する
        participants:
          type: string
          nullable: true
          description: 参加者(自由記述)
      required:
        - deal_id
        - genre
        - assignee_ids
        - participants
      example:
        deal_id: Rb7XkQpYz3Lh9vMs2N
        genre: 初回商談
        assignee_ids:
          - Ub3MqTzW5Ly8Nc1KsP
        participants: 先方 佐藤様
    ErrorCode:
      type: string
      description: |
        機械可読なエラー種別。HTTP ステータスと 1 対 1 ではない(`400` は
        `validation_error` と `invalid_request` の両方を取り得る)ため、
        クライアントは**このコードで分岐する**こと。
        今後の追加に備え、未知のコードは汎用エラーとして扱うこと。

        1.1.0 で追加:
        - `quota_exceeded` — 録音の所有者の文字起こし利用枠・予算の超過(`403`)。月内は解消しないため自動リトライしない
        - `invalid_state` — 対象の状態が操作を許さない(`409`)。理由は `error.reason`
      enum:
        - invalid_request
        - validation_error
        - unauthorized
        - forbidden
        - not_found
        - rate_limited
        - internal_error
        - quota_exceeded
        - invalid_state
    FieldError:
      type: object
      description: バリデーション失敗時のフィールド単位の詳細
      properties:
        name:
          type: string
          description: 対象フィールドのパス。`properties` 配下は `properties.<api_name>` で表す
          example: properties.name
        code:
          type: string
          description: >
            フィールド単位のエラー種別。

            `required` / `invalid_type` / `invalid_value` / `not_found` /
            `unknown_property` / `read_only` /

            `too_long` / `out_of_range` のいずれか。
          example: required
        message:
          type: string
          description: 人間向けの説明文(日本語)
          example: この項目は必須です。
      required:
        - name
        - code
        - message
    InvalidStateReason:
      type: string
      description: |
        `invalid_state` の理由。今後の追加に備え、未知の値は汎用の状態エラーとして扱うこと
      enum:
        - no_meeting_url
        - meeting_ended
        - event_cancelled
        - bot_in_call
        - not_scheduled
  responses:
    BadRequest:
      description: バリデーション失敗
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 認証失敗(キー欠落・不正・失効・IP 拒否)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: スコープ不足
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: レート制限超過(`Retry-After` ヘッダあり)
      headers:
        Retry-After:
          schema:
            type: integer
          description: 次のリクエストまでの待機秒数
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: sk_*
      description: |
        Stockwork が発行する API キー(`sk_` プレフィックス、base62 ランダム ≥ 40 文字)。
        キーには 1 つの role(`read` / `analyst` / `write` / `admin`)が紐付き、
        各エンドポイントの必要 role 以上であることが要求される(対応表は info.description 参照)。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.