{"openapi":"3.0.0","components":{"examples":{},"headers":{},"parameters":{},"requestBodies":{},"responses":{},"schemas":{"VersionResponse":{"properties":{"version":{"type":"string"}},"required":["version"],"type":"object"},"CopyTabResponse":{"properties":{"destination_spreadsheet_id":{"type":"string"},"sheet_id":{"type":"number","format":"double","description":"Numeric tab id (`gid`) of the newly created tab in the destination."},"title":{"type":"string","description":"Title the new tab actually carries — always Google's \"Copy of <original>\"."}},"required":["destination_spreadsheet_id","sheet_id","title"],"type":"object","additionalProperties":false},"CopyTabRequest":{"properties":{"sheet_id":{"type":"integer","format":"int32","description":"Numeric tab id (`gid`) of the tab to copy. Provide exactly one of\n`sheet_id` or `sheet_name`.","minimum":0},"sheet_name":{"type":"string","description":"Exact title of the tab to copy. Provide exactly one of `sheet_id` or\n`sheet_name`."},"destination_spreadsheet_id":{"type":"string","description":"Spreadsheet to copy the tab into — a Google Spreadsheet ID or URL. May be\nthe source spreadsheet itself, which duplicates the tab in place."}},"required":["destination_spreadsheet_id"],"type":"object","additionalProperties":false},"ModelOption":{"properties":{"id":{"type":"string"},"label":{"type":"string"},"provider":{"type":"string"},"is_default":{"type":"boolean"}},"required":["id","label","provider","is_default"],"type":"object","additionalProperties":false},"ConfigurationResponse":{"properties":{"models":{"properties":{"defaults":{"properties":{"bulk_search_model":{"type":"string"},"bulk_model":{"type":"string"},"agent_model":{"type":"string"}},"type":"object"},"bulk_search_models":{"items":{"$ref":"#/components/schemas/ModelOption"},"type":"array"},"bulk_models":{"items":{"$ref":"#/components/schemas/ModelOption"},"type":"array"},"agent_models":{"items":{"$ref":"#/components/schemas/ModelOption"},"type":"array"}},"required":["defaults","bulk_search_models","bulk_models","agent_models"],"type":"object"}},"required":["models"],"type":"object","additionalProperties":false},"VerifyApiKeyResponse":{"properties":{"webhook_secret":{"type":"string","nullable":true},"google_connected":{"type":"boolean"},"space":{"properties":{"name":{"type":"string","nullable":true},"id":{"type":"string"}},"required":["name","id"],"type":"object"},"user":{"properties":{"email":{"type":"string","nullable":true}},"required":["email"],"type":"object"},"valid":{"type":"boolean"}},"required":["webhook_secret","google_connected","space","user","valid"],"type":"object"},"AgentStatus":{"type":"string","enum":["active","idle"]},"AgentModels":{"properties":{"agent_model":{"type":"string"},"bulk_model":{"type":"string"},"bulk_search_model":{"type":"string"}},"required":["agent_model","bulk_model","bulk_search_model"],"type":"object","additionalProperties":false},"Record_string.unknown_":{"properties":{},"additionalProperties":{},"type":"object","description":"Construct a type with a set of properties K of type T"},"TurnUsage":{"description":"Credit usage for one turn, in integer nano-dollars (divide by 1_000_000_000\nfor the dollar value): `agent_usage` covers the reasoning agent's own model\ncalls, `tool_usage` the tools it ran, `total_usage` their sum.","properties":{"agent_usage":{"type":"number","format":"double"},"tool_usage":{"type":"number","format":"double"},"total_usage":{"type":"number","format":"double"}},"required":["agent_usage","tool_usage","total_usage"],"type":"object","additionalProperties":false},"UserMessageEntry":{"properties":{"type":{"type":"string","enum":["user_message"],"nullable":false},"turn_id":{"type":"string"},"message_id":{"type":"string"},"created_at":{"type":"string"},"content":{"type":"string"}},"required":["type","turn_id","message_id","created_at","content"],"type":"object","additionalProperties":false},"AssistantMessageEntry":{"properties":{"type":{"type":"string","enum":["assistant_message"],"nullable":false},"turn_id":{"type":"string"},"message_id":{"type":"string"},"created_at":{"type":"string"},"content":{"type":"string"}},"required":["type","turn_id","message_id","created_at","content"],"type":"object","additionalProperties":false},"BulkRowCounts":{"description":"Row counters for bulk tool calls. `processed` counts successful rows.","properties":{"processed":{"type":"number","format":"double"},"errors":{"type":"number","format":"double"},"total":{"type":"number","format":"double"}},"type":"object","additionalProperties":false},"ReadRangeDimensions":{"description":"Dimensions of the data a `read_range` call returned — counts only, never\ncell contents. Totals are across every sheet the read spanned. `cells`\ncounts the cells actually returned (the Sheets API omits trailing empties,\nso this is not necessarily `rows × columns`).","properties":{"sheets":{"type":"number","format":"double","description":"Number of sheets the returned data spans."},"rows":{"type":"number","format":"double","description":"Distinct rows per sheet, summed across the sheets the read spanned."},"columns":{"type":"number","format":"double","description":"Distinct columns per sheet, summed across the sheets the read spanned."},"cells":{"type":"number","format":"double","description":"Cells actually returned."}},"required":["sheets","rows","columns","cells"],"type":"object","additionalProperties":false},"Pick_AgentToolCall.Exclude_keyofAgentToolCall.id-or-processed-or-errors-or-total-or-arguments-or-data-or-seq-or-status__":{"properties":{"created_at":{"type":"string","description":"When the tool call started."},"completed_at":{"type":"string","description":"When the tool call reached a terminal status (`completed`/`error`)."},"tool":{"type":"string"},"range":{"type":"string","description":"Affected range, e.g. \"Sheet1!A1:A40\" (mirrors the add-on display)."},"updated_range":{"type":"string","description":"Bulk tools: the range actually written (replaces `range` on bulk entries)."},"rows":{"$ref":"#/components/schemas/BulkRowCounts","description":"Bulk tools: row counters."},"prompt_template":{"type":"string","description":"Bulk tools: the per-row prompt template (column refs as `{{A}}`)."},"column":{"type":"string","description":"Output column for column-oriented tools. Internal — not returned for bulk."},"skill":{"type":"string","description":"Skill name(s) for `load_skill` / `create_skill`."},"sheet_name":{"type":"string","description":"Sheet the tool operated on (range tools, overview, spreadsheet fields)."},"cells":{"type":"number","format":"double","description":"Cells affected by the call: cells written for `write_range`, source-range\ncell count for `copy_paste_range` (when the range is bounded)."},"read":{"$ref":"#/components/schemas/ReadRangeDimensions","description":"read_range: dimensions of the data returned (counts only, no contents)."},"paste_type":{"type":"string","description":"copy_paste_range: the paste behaviour (e.g. PASTE_VALUES_ONLY)."},"source_range":{"type":"string","description":"copy_paste_range: the range copied from."},"target_range":{"type":"string","description":"copy_paste_range: the range pasted into."},"source_sheet":{"type":"string","description":"copy_paste_range: the sheet copied from, when the source range named\none. For cross-sheet copies this differs from `sheet_name` (which is\nthe destination)."},"target_sheet":{"type":"string","description":"copy_paste_range: the sheet pasted into, when the target range named one."},"fields":{"type":"string","description":"read_spreadsheet_fields: the requested field mask."},"query":{"type":"string","description":"web_search: the query searched for (the tool's prompt)."},"number_of_searches":{"type":"number","format":"double","description":"web_search: how many searches the tool ran (one billed unit each)."},"sources":{"items":{"type":"string"},"type":"array","description":"web_search: the source URLs the searches surfaced, deduplicated."},"message":{"type":"string","description":"Result message. Only present when the call errored (carries the reason)."}},"required":["created_at","tool"],"type":"object","description":"From T, pick a set of properties whose keys are in the union K"},"ToolCallEntry":{"description":"A tool call in the conversation, with its result embedded once the call\nreaches a terminal status (`status` / `completed_at` / summary details\nupdate in place — mirroring the add-on, which shows one card per tool call).","properties":{"created_at":{"type":"string","description":"When the tool call started."},"completed_at":{"type":"string","description":"When the tool call reached a terminal status (`completed`/`error`)."},"tool":{"type":"string"},"range":{"type":"string","description":"Affected range, e.g. \"Sheet1!A1:A40\" (mirrors the add-on display)."},"updated_range":{"type":"string","description":"Bulk tools: the range actually written (replaces `range` on bulk entries)."},"rows":{"$ref":"#/components/schemas/BulkRowCounts","description":"Bulk tools: row counters."},"prompt_template":{"type":"string","description":"Bulk tools: the per-row prompt template (column refs as `{{A}}`)."},"column":{"type":"string","description":"Output column for column-oriented tools. Internal — not returned for bulk."},"skill":{"type":"string","description":"Skill name(s) for `load_skill` / `create_skill`."},"sheet_name":{"type":"string","description":"Sheet the tool operated on (range tools, overview, spreadsheet fields)."},"cells":{"type":"number","format":"double","description":"Cells affected by the call: cells written for `write_range`, source-range\ncell count for `copy_paste_range` (when the range is bounded)."},"read":{"$ref":"#/components/schemas/ReadRangeDimensions","description":"read_range: dimensions of the data returned (counts only, no contents)."},"paste_type":{"type":"string","description":"copy_paste_range: the paste behaviour (e.g. PASTE_VALUES_ONLY)."},"source_range":{"type":"string","description":"copy_paste_range: the range copied from."},"target_range":{"type":"string","description":"copy_paste_range: the range pasted into."},"source_sheet":{"type":"string","description":"copy_paste_range: the sheet copied from, when the source range named\none. For cross-sheet copies this differs from `sheet_name` (which is\nthe destination)."},"target_sheet":{"type":"string","description":"copy_paste_range: the sheet pasted into, when the target range named one."},"fields":{"type":"string","description":"read_spreadsheet_fields: the requested field mask."},"query":{"type":"string","description":"web_search: the query searched for (the tool's prompt)."},"number_of_searches":{"type":"number","format":"double","description":"web_search: how many searches the tool ran (one billed unit each)."},"sources":{"items":{"type":"string"},"type":"array","description":"web_search: the source URLs the searches surfaced, deduplicated."},"message":{"type":"string","description":"Result message. Only present when the call errored (carries the reason)."},"type":{"type":"string","enum":["tool_call"],"nullable":false},"turn_id":{"type":"string"},"tool_call_id":{"type":"string","description":"Tool-call identifier (matches the backend's logged function-call id)."},"status":{"type":"string","enum":["pending","running","succeeded","failed","cancelled"],"description":"Terminal outcomes are reported uniformly as `succeeded` / `failed` for\nevery tool (for bulk tools, `succeeded` means all rows processed without\nfailures). The internal storage values (`completed`/`error`) never appear\nin responses — the projection rewrites them — so the public contract\nadvertises only externally observable values."}},"required":["created_at","tool","type","turn_id","tool_call_id","status"],"type":"object","additionalProperties":false},"MessageEntry":{"anyOf":[{"$ref":"#/components/schemas/UserMessageEntry"},{"$ref":"#/components/schemas/AssistantMessageEntry"},{"$ref":"#/components/schemas/ToolCallEntry"}]},"Agent":{"properties":{"id":{"type":"string"},"spreadsheet_id":{"type":"string"},"status":{"$ref":"#/components/schemas/AgentStatus"},"created_at":{"type":"string"},"last_activity_at":{"type":"string","nullable":true},"number_of_turns":{"type":"number","format":"double","description":"Total number of turns in this agent's conversation, including the\none in progress when the agent is `active`."},"models":{"allOf":[{"$ref":"#/components/schemas/AgentModels"}],"nullable":true,"description":"The effective models for this agent (the most recent turn's), or `null`\nif none. Always returned."},"error_message":{"type":"string","nullable":true,"description":"The latest turn's error message (failure reason), or `null` when it has not\nerrored. Always returned — errored turns produce no assistant message, so\nthis is where the failure surfaces."},"error_code":{"type":"string","nullable":true,"description":"The latest turn's gpt-errors code, or `null` when it has not errored or the\nfailure carried no code. Lets a client branch on the condition instead of\nmatching the message (GPT-4710)."},"error_params":{"allOf":[{"$ref":"#/components/schemas/Record_string.unknown_"}],"nullable":true,"description":"The params `error_message` was rendered with, for a per-surface re-render."},"usage":{"allOf":[{"$ref":"#/components/schemas/TurnUsage"}],"nullable":true,"description":"The latest turn's final credit usage in integer nano-dollars (divide by\n1_000_000_000 for dollars), or `null` when unavailable. Always returned,\nand always terminal: `null` while a turn is still running (see\n`usage_so_far` for the running subtotal). Turns that ran to their natural\nend report the figure the runtime settled on; turns that were cancelled or\nfailed report the charges accumulated before they stopped."},"usage_so_far":{"allOf":[{"$ref":"#/components/schemas/TurnUsage"}],"nullable":true,"description":"The running credit subtotal of the turn currently in flight, in the same\nunits as `usage`. Present only while the latest turn is active, and only\nthen — so `usage` keeps meaning \"final\" and a consumer summing it does not\ndouble-count. Rises monotonically as the turn is charged, and is `null`\nwhen the turn has not been charged yet or its accumulator entry has\nexpired (GPT-4719)."},"messages":{"items":{"$ref":"#/components/schemas/MessageEntry"},"type":"array","description":"The latest turn's messages as a flat, ordered, type-tagged array. Always\nreturned. The full conversation across all turns is available from\n`GET /agents/{id}/messages` (paginated)."}},"required":["id","spreadsheet_id","status","created_at","last_activity_at","number_of_turns","models","error_message","error_code","usage","messages"],"type":"object","additionalProperties":false},"RunAgentRequest":{"properties":{"prompt":{"type":"string"},"agent_id":{"type":"string"},"spreadsheet_id":{"type":"string"},"document_id":{"type":"string","deprecated":true},"sheet_name":{"type":"string"},"sheet_id":{"type":"integer","format":"int32","description":"Numeric tab id — the `gid` from a Google Sheets URL. Resolved\nserver-side to the tab title. When both `sheet_id` and `sheet_name`\nare provided they must reference the same tab. Also inferred from a\n`gid` in a full spreadsheet URL passed as `spreadsheet_id`.","minimum":0},"agent_model":{"type":"string"},"bulk_model":{"type":"string"},"bulk_search_model":{"type":"string"},"webhook_url":{"type":"string"}},"required":["prompt"],"type":"object","additionalProperties":false},"AgentMessagesPage":{"description":"Paginated conversation page returned by `GET /agents/{id}/messages`.","properties":{"messages":{"items":{"$ref":"#/components/schemas/MessageEntry"},"type":"array","description":"Ordered, type-tagged conversation entries for this page."},"end_cursor":{"type":"string","nullable":true,"description":"Cursor of the last entry on this page; pass it as `after` to fetch the\nnext page. `null` when the page is empty."},"has_next_page":{"type":"boolean"},"total":{"type":"number","format":"double","description":"Total number of entries in the full conversation."}},"required":["messages","end_cursor","has_next_page","total"],"type":"object","additionalProperties":false}},"securitySchemes":{"api_key":{"type":"http","scheme":"bearer"}}},"info":{"title":"GPT for Work Public API","version":"0.1.0","description":"Public API bootstrap service","license":{"name":"UNLICENSED"},"contact":{}},"paths":{"/version":{"get":{"operationId":"GetVersion","responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}}},"tags":["Status"],"security":[],"parameters":[]}},"/v1/{platform}/spreadsheets/{source_id}/tabs/copy":{"post":{"operationId":"CopyTab","responses":{"200":{"description":"Copied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyTabResponse"}}}}},"description":"Copy one tab of the source spreadsheet into a destination spreadsheet.\n\nThe destination may be the source itself (duplicates the tab in place).\nThe caller needs read access to the source and write access to the\ndestination. The copied tab keeps its values, formulas, formatting, notes\nand embedded charts, and is appended as the last tab of the destination;\nformulas referencing other tabs of the source may not resolve when copied\nto a different spreadsheet.\n\nNot idempotent: every successful call creates a new tab, so do not retry\na call that may have succeeded (including timeouts).","tags":["Spreadsheets"],"security":[],"parameters":[{"in":"path","name":"platform","required":true,"schema":{"type":"string"}},{"in":"path","name":"source_id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyTabRequest"}}}}}},"/v1/{platform}/agents/configuration":{"get":{"operationId":"GetConfiguration","responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigurationResponse"}}}}},"tags":["Agents"],"security":[],"parameters":[{"in":"path","name":"platform","required":true,"schema":{"type":"string"}}]}},"/v1/auth/verify":{"get":{"operationId":"Verify","responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyApiKeyResponse"}}}}},"tags":["Auth"],"security":[],"parameters":[]}},"/v1/{platform}/agents":{"post":{"operationId":"RunAgent","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}}},"tags":["Agents"],"security":[],"parameters":[{"in":"path","name":"platform","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunAgentRequest"}}}}}},"/v1/{platform}/agents/{id}":{"get":{"operationId":"GetAgent","responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}}},"description":"Retrieve an agent's current status and the latest turn's conversation. The\nresponse carries `id`, `spreadsheet_id`, `status`, `created_at`,\n`last_activity_at`, `number_of_turns`, the effective `models`, the latest\nturn's `error_message`, and `messages` — the latest turn as a single ordered\narray (user messages, assistant messages, and tool calls with compact\nsummaries). The full conversation across all turns is paginated via\n`GET {id}/messages`.","tags":["Agents"],"security":[],"parameters":[{"in":"path","name":"platform","required":true,"schema":{"type":"string"}},{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Set to `false` to omit a failed\ntool-call attempt when a later tool call in the latest turn succeeds.\nTerminal tool-call failures and the turn's `error_message` remain\nvisible. Defaults to `true` for backward compatibility. This does not\naffect the paginated messages endpoint.","in":"query","name":"include_intermediate_tool_failures","required":false,"schema":{"type":"boolean"}}]}},"/v1/{platform}/agents/{id}/messages":{"get":{"operationId":"GetAgentMessages","responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMessagesPage"}}}}},"description":"Retrieve the full conversation across all turns, paginated.","tags":["Agents"],"security":[],"parameters":[{"in":"path","name":"platform","required":true,"schema":{"type":"string"}},{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Cursor returned as `end_cursor` by a previous page; entries\nstrictly after it are returned.","in":"query","name":"after","required":false,"schema":{"type":"string"}},{"description":"Page size, 1–100 (default 20).","in":"query","name":"limit","required":false,"schema":{"format":"double","type":"number"}}]}},"/v1/{platform}/agents/{id}/stop":{"post":{"operationId":"StopAgent","responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}}},"tags":["Agents"],"security":[],"parameters":[{"in":"path","name":"platform","required":true,"schema":{"type":"string"}},{"in":"path","name":"id","required":true,"schema":{"type":"string"}}]}}},"servers":[{"url":"/"}]}