> ## 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_after` で増分取得可能。
文字起こし(`transcript_text`)と AI 要約(`summary`)は含まれない。
必要なレコードを `GET /v1/meeting-records/{record_id}/` で個別に取得する。

`updated_at` は録音の作成・状態遷移・文字起こし完了・取引/ジャンル等の編集で進む。
AI 要約(`summary`)の生成・再生成では進まない。




## OpenAPI

````yaml /openapi/v1.yaml get /v1/meeting-records/
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/meeting-records/:
    get:
      tags:
        - Meeting Records
      summary: 商談音声を一覧取得
      description: |
        組織内の商談音声をカーソルページネーションで返す。`updated_after` で増分取得可能。
        文字起こし(`transcript_text`)と AI 要約(`summary`)は含まれない。
        必要なレコードを `GET /v1/meeting-records/{record_id}/` で個別に取得する。

        `updated_at` は録音の作成・状態遷移・文字起こし完了・取引/ジャンル等の編集で進む。
        AI 要約(`summary`)の生成・再生成では進まない。
      parameters:
        - $ref: '#/components/parameters/UpdatedAfter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: 一覧取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeetingRecordListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - BearerApiKey: []
components:
  parameters:
    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:
    MeetingRecordListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/MeetingRecord'
        paging:
          $ref: '#/components/schemas/Paging'
      required:
        - results
        - paging
    MeetingRecord:
      type: object
      description: |
        商談音声(Meeting Record)。Web 会議 Bot・ファイルアップロード・電話連携・スマホ録音で
        取り込まれた録音・録画 1 件と、その文字起こしを表す。**読み取り専用**
        (作成・更新は GUI と各連携が行う)。

        商談ログ(Meeting Log)へ登録済みのものは `properties.meeting_log_ids` に、
        コンタクト活動へ登録済みのものは `properties.contact_activity_ids` に、登録先の
        record_id が入る(1 つの商談音声を複数の取引・コンタクトに登録できるため配列。未登録なら `[]`)。
        取引へは `properties.deal_id` で紐づく(任意)。

        この schema は**一覧・検索の要素**。文字起こし(`transcript_text`)と AI 要約(`summary`)は
        単一レコード表現(`MeetingRecordDetail`)にのみ含まれる。
      properties:
        id:
          type: string
          description: Stockwork record_id(18 文字)
          example: Mr7XkQpYz3Lh9vMs2N
        properties:
          allOf:
            - $ref: '#/components/schemas/PropertiesMap'
          description: >
            商談音声のプロパティ集合。すべて読み取り専用。


            - `source_type` — 取得元(Teams / Zoom / Google Meet / ファイル / 電話連携 /
            スマホ録音 等)。
              選択肢は `GET /v1/meeting-records/properties/` の `options`
            - `status` — 処理ステータス。`reserved`(予約のみ)/ `pending` / `processing` の間は
              文字起こしが未完成。`available`(登録可能)/ `registered`(商談ログ等に登録済み)/
              `error`
            - `transcription_status` — 文字起こしの状態。`completed` で全文が確定する

            - `visibility` — `private`(作成者と共有メンバーのみ)/ `public`(組織内公開)。API キーには
              `public` のものだけが返る(登録して商談ログ等になると `public` に変わる)
            - `assignee_ids` — 担当者(User)の record_id の配列。`GET /v1/users/` で解決する

            - `duration_seconds` — 録音時間(秒)。文字起こし未完了時は `null`

            - `transcript_text` — 文字起こしの平文。`MM:SS --> MM:SS`(分は 60 を超えうる)の
              時刻行と `話者: 発言` の対を空行で区切って並べる。**詳細取得の応答にのみ含まれる**
              (一覧・検索にはキー自体が無い)
            - 組織別カスタムプロパティも同じ namespace で返る


            `created_by_name`、`tags`(タグ名の配列)、`access_level`(`private` / `org` /
            `external`)、

            `link_status`(`approved` / `has_suggestion` /
            `unlinked`。承認済みと提案の両方があれば `approved`)も返す。
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          description: >-
            レコードの値が最後に変わった日時。コアフィールド・カスタムプロパティ・アクティビティ件数などの集計値のいずれかが実際に変わったときに進む。商談ログやメールなどの活動を記録した場合も、それが集計値を動かすためこの日時が進む。同じ値での再保存や、他レコードとの紐付け変更では進まない。
      required:
        - id
        - properties
        - created_at
        - updated_at
      example:
        id: Mr7XkQpYz3Lh9vMs2N
        properties:
          name: 株式会社サンプル 初回商談
          source_type: teams
          status: registered
          transcription_status: completed
          visibility: public
          deal_id: Rb7XkQpYz3Lh9vMs2N
          genre: 初回商談
          assignee_ids:
            - Ub3MqTzW5Ly8Nc1KsP
          participants: 山田, 佐藤
          scheduled_start_time: '2026-09-01T05:00:00Z'
          actual_start_time: '2026-09-01T05:02:10Z'
          actual_end_time: '2026-09-01T05:58:40Z'
          duration_seconds: 3390.5
          created_by_id: Us7XkQpYz3Lh9vMs2N
          meeting_log_ids:
            - Ml4aB9xY2zKt7Qw1Pn
          contact_activity_ids: []
        created_at: '2026-09-01T05:00:00Z'
        updated_at: '2026-09-01T06:10: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: この項目は必須です。
    PropertiesMap:
      type: object
      description: |
        プロパティの集合。キーは `api_name`、値は `PropertyValue`。
        コアフィールドと組織別カスタムプロパティが同じ namespace に並ぶ。
        利用可能なキーと型は `GET /v1/<resource>/properties/` で取得する。
      additionalProperties:
        $ref: '#/components/schemas/PropertyValue'
    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
    PropertyValue:
      description: |
        プロパティの値。文字列・数値・真偽値・文字列の配列・null のいずれか。
        配列になるのは MULTI_SELECT 型と、`meeting_log_ids` のような record_id の一覧。

        - **キーを送らない** = そのプロパティは変更しない(PATCH は部分更新)
        - **明示的に `null` を送る** = そのプロパティの値をクリアする

        作成(`POST`)時の `null` は「値なしで作成」と同義。
        必須プロパティに `null` を送った場合は `400`。

        (OpenAPI 3.0 では union に null 型を直接書けないため、`anyOf` の各分岐に
        `nullable: true` を付けて表現している。`oneOf` にすると null が全分岐にマッチして
        「ちょうど 1 つ」の条件を満たせない。)
      anyOf:
        - type: string
          nullable: true
        - type: number
          nullable: true
        - type: boolean
          nullable: true
        - type: array
          items:
            type: string
          nullable: true
  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.