---
title: "Register workbook installation"
method: POST
path: "/v1/workbook-installations"
tags: ["Filing-to-Model Workbooks"]
---

# Register workbook installation

`POST /v1/workbook-installations`

## Request

- Base URL: `https://api.turos.app`
- URL: `https://api.turos.app/v1/workbook-installations`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Registers an Excel or Google Sheets workbook as a durable, server-owned workbook identity used by Excel, Sheets, MCP, and API filing-to-model workflows. The server holds the record of mappings, refresh history, provenance, and audit events.

## Request body

- WorkbookInstallationCreateBody
  - `host` 'excel_windows' | 'excel_mac' | 'excel_web' | 'sheets', required
  - `workbookIdentityKey` string, required
  - `workbookFingerprintHash` string, required
  - `copiedFromWorkbookInstallationId` string, nullable
  - `workbookMetadata` object, required

## Response `201`

Workbook installation created

- object
  - `object` 'workbook_installation', required
  - `workbookInstallation` WorkbookInstallation, required
    - `workbookInstallationId` string, required
    - `organizationId` string, required
    - `createdByUserId` string, nullable
    - `host` 'excel_windows' | 'excel_mac' | 'excel_web' | 'sheets', required
    - `workbookIdentityKey` string, required
    - `workbookFingerprintHash` string, required
    - `installationVersion` integer, required
    - `installedAt` string, date-time, required
    - `lastOpenedAt` string, date-time, nullable
    - `revokedAt` string, date-time, nullable
    - `copiedFromWorkbookInstallationId` string, nullable
  - `requestId` string, required

## Other responses

- `default`: Contract-aware error response

---

[API](https://skmtc.dev/turos/apis/turos-api.md) · [All operations](https://skmtc.dev/turos/apis/turos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/turos/apis/turos-api/revisions/a68d3ec80a56?raw)