> ## 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.

# カレンダー連携状況を一覧取得

> 組織内でカレンダーを連携しているユーザーと、その状態を返す。
予定が取り込まれていない場合の切り分けに使う(連携していない人の予定は取り込まれない)。




## OpenAPI

````yaml /openapi/v1.yaml get /v1/calendar-connections/
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-connections/:
    get:
      tags:
        - Calendar Connections
      summary: カレンダー連携状況を一覧取得
      description: |
        組織内でカレンダーを連携しているユーザーと、その状態を返す。
        予定が取り込まれていない場合の切り分けに使う(連携していない人の予定は取り込まれない)。
      parameters:
        - $ref: '#/components/parameters/UpdatedAfter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: 一覧取得成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalendarConnectionListResponse'
        '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:
    CalendarConnectionListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CalendarConnection'
        paging:
          $ref: '#/components/schemas/Paging'
      required:
        - results
        - paging
    CalendarConnection:
      type: object
      description: ユーザー 1 人のカレンダー連携状況。1 ユーザーにつき最大 1 件
      properties:
        user_id:
          type: string
          description: 連携しているユーザーの record_id
        platform:
          type: string
          enum:
            - microsoft_outlook
            - google_calendar
        email:
          type: string
          description: 連携しているカレンダーのアカウント(メールアドレス)
        status:
          type: string
          enum:
            - active
            - disconnected
            - error
          description: |
            `disconnected` はカレンダー側で連携が切れた状態、`error` は同期に失敗している状態。
            再連携は画面で行う
        last_synced_at:
          type: string
          format: date-time
          nullable: true
          description: 最後に予定を同期した日時
      required:
        - user_id
        - platform
        - email
        - status
        - last_synced_at
      example:
        user_id: Us7XkQpYz3Lh9vMs2N
        platform: microsoft_outlook
        email: yamada@example.co.jp
        status: active
        last_synced_at: '2026-09-28T02:03: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: この項目は必須です。
    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.