> ## Documentation Index > Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt > Use this file to discover all available pages before exploring further. # Ragic API reference > API reference for the Ragic plugin in Corsair: every `ragic.api.*` operation with its input and output types, taken from the plugin's Zod schemas. > [!NOTE] > > **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling). ## Records ### comment `records.comment` Post a comment on a record and return the comment that was added **Risk:** `write` ```ts theme={null} await corsair.ragic.api.records.comment({ account: 'demo', path: '/sales', sheetIndex: 1, recordId: 2, comment: 'Please review this order.' }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `account` | `string` | Yes | The account name from your Ragic URL, such as "demo" in [www.ragic.com/demo/sales](http://www.ragic.com/demo/sales). | | `path` | `string` | Yes | The folder path from your URL, starting with a slash, such as /sales. | | `sheetIndex` | `number` | Yes | The sheet number from your URL, the number after the folder path. | | `recordId` | `number` | Yes | The record id, which is the \_ragicId value. | | `comment` | `string` | Yes | The comment text. | **Output:** `Record>` *** ### create `records.create` Create a record from field ID to value, including subtable rows grouped by negative row id, with control over formulas, workflows, AI Agents and notifications **Risk:** `write` ```ts theme={null} await corsair.ragic.api.records.create({ account: 'demo', path: '/sales', sheetIndex: 1, fields: { '2000123': 'Dunder Mifflin', '1000001': ['Customer', 'Reseller'], '_subtable_2000154': { '-1': { '2000147': 'Bill' } } } }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `account` | `string` | Yes | The account name from your Ragic URL, such as "demo" in [www.ragic.com/demo/sales](http://www.ragic.com/demo/sales). | | `path` | `string` | Yes | The folder path from your URL, starting with a slash, such as /sales. | | `sheetIndex` | `number` | Yes | The sheet number from your URL, the number after the folder path. | | `fields` | `Record` | Yes | Field ID to value. A multi-select takes an array; a date needs yyyy/MM/dd or yyyy/MM/dd HH:mm:ss; a subtable is `_subtable_` keyed by a negative row id that groups a row’s values. | | `doFormula` | `boolean` | No | Recalculate every formula before saving. | | `doDefaultValue` | `boolean` | No | Load every default value before saving. | | `doLinkLoad` | `boolean \| first` | No | Run link and load operations: true after the formula recalculation, "first" before it. Either way doFormula must also be set when a recalculation is needed. | | `doWorkflow` | `boolean` | No | False skips the workflow scripts, which otherwise run. | | `doAIAgent` | `boolean` | No | False skips the AI Agents, which otherwise run. | | `notification` | `boolean` | No | Defaults to true: the save sends notifications. | | `doValidation` | `boolean` | No | Run the sheet’s field validation rules first. A failing field rejects the save. | | `checkLock` | `boolean` | No | Refuse the update when the record is locked. Without it Ragic ignores the lock and saves the update. | **Output** | Name | Type | Required | Description | | - | - | - | - | | `status` | `string \| null` | No | SUCCESS when the record was saved. | | `msg` | `string \| null` | No | — | | `ragicId` | `number \| null` | No | The record id (\_ragicId). | | `rv` | `any` | No | — | | `data` | `Record \| null` | No | The saved record, keyed by field ID, with its reserved keys. | *** ### delete `records.delete` Delete one record by id. Ragic moves it to the sheet's recycle bin, where it can be restored from the Ragic UI **Risk:** `destructive` ```ts theme={null} await corsair.ragic.api.records.delete({ account: 'demo', path: '/sales', sheetIndex: 1, recordId: 3 }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `account` | `string` | Yes | The account name from your Ragic URL, such as "demo" in [www.ragic.com/demo/sales](http://www.ragic.com/demo/sales). | | `path` | `string` | Yes | The folder path from your URL, starting with a slash, such as /sales. | | `sheetIndex` | `number` | Yes | The sheet number from your URL, the number after the folder path. | | `recordId` | `number` | Yes | The record id, which is the \_ragicId value. | **Output** | Name | Type | Required | Description | | - | - | - | - | | `msg` | `string \| null` | No | Says the record went to the recycle bin. | | `ragicId` | `number \| null` | No | The deleted record id. | | `status` | `string \| null` | No | — | *** ### get `records.get` Read one record by id, optionally with its subtable, comments, history or unmasked fields. An unknown or deleted id answers an empty object **Risk:** `read` ```ts theme={null} await corsair.ragic.api.records.get({ account: 'demo', path: '/sales', sheetIndex: 1, recordId: 12345 }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `account` | `string` | Yes | The account name from your Ragic URL, such as "demo" in [www.ragic.com/demo/sales](http://www.ragic.com/demo/sales). | | `path` | `string` | Yes | The folder path from your URL, starting with a slash, such as /sales. | | `sheetIndex` | `number` | Yes | The sheet number from your URL, the number after the folder path. | | `recordId` | `number` | Yes | The record id, which is the \_ragicId value. | | `naming` | `EID \| FNAME` | No | — | | `subtables` | `boolean` | No | — | | `info` | `boolean` | No | — | | `comment` | `boolean` | No | — | | `history` | `boolean` | No | — | | `ignoreMask` | `boolean` | No | Unmask masked text, when your groups allow it. | **Output:** `Record>` *** ### list `records.list` List records from a sheet with filters, full-text search, a saved view, paging and ordering; pass a taskId to check a mass operation instead **Risk:** `read` ```ts theme={null} await corsair.ragic.api.records.list({ account: 'demo', path: '/sales', sheetIndex: 1, where: [{ fieldId: 2000123, op: 'eq', value: 'Alphabet Inc.' }], limit: 50 }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `account` | `string` | Yes | The account name from your Ragic URL, such as "demo" in [www.ragic.com/demo/sales](http://www.ragic.com/demo/sales). | | `path` | `string` | Yes | The folder path from your URL, starting with a slash, such as /sales. | | `sheetIndex` | `number` | Yes | The sheet number from your URL, the number after the folder path. | | `where` | `object[]` | No | Filter conditions. Several on the same field combine as the docs describe. | | `fts` | `string` | No | A full-text search term. | | `filterId` | `number` | No | A saved Shared View id, as an alternative to building filters. | | `limit` | `number` | No | How many records to return. Defaults to 1,000; above that, set it explicitly. | | `offset` | `number` | No | How many records to skip first. | | `taskId` | `string` | No | Check a mass operation’s progress instead of listing records. | | `order` | `object` | No | Sort by one field. | | `reverse` | `boolean` | No | Reverse the default creation-date ordering, newest first. | | `naming` | `EID \| FNAME` | No | Name each field in the response by its ID (EID) or its name (FNAME, the default). | | `subtables` | `boolean` | No | False omits subtable data, which makes the response much smaller. | | `listing` | `boolean` | No | True returns only the fields shown on the listing page. | | `fetchDomainIds` | `(number \| string)[]` | No | Return only these field IDs. | | `info` | `boolean` | No | Add create date and create user to each record. | | `comment` | `boolean` | No | Add the comment thread to each record. | | `history` | `boolean` | No | Add the edit history to each record. | | `conversation` | `boolean` | No | Add the email conversation to each record. | | `approval` | `boolean` | No | Add the approval information to each record. | > [accordion] where full type > > ```ts theme={null} > { > fieldId: number | string, > op: eq | regex | gte | lte | gt | lt | like | eqeq, > value?: string | number > }[] > ``` > [accordion] order full type > > ```ts theme={null} > { > fieldId: number | string, > direction: ASC | DESC > } > ``` **Output:** `Record> \| object` > [accordion] Output full type > > ```ts theme={null} > Record> | { > status: string, > progress?: number | null, > total?: number | null, > message?: string | null > } > ``` *** ### lock `records.lock` Lock a record so it cannot be edited in the Ragic UI until it is unlocked; an API update still saves unless it passes checkLock: true. The same permission as locking in the form **Risk:** `write` ```ts theme={null} await corsair.ragic.api.records.lock({ account: 'demo', path: '/sales', sheetIndex: 1, recordId: 102 }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `account` | `string` | Yes | The account name from your Ragic URL, such as "demo" in [www.ragic.com/demo/sales](http://www.ragic.com/demo/sales). | | `path` | `string` | Yes | The folder path from your URL, starting with a slash, such as /sales. | | `sheetIndex` | `number` | Yes | The sheet number from your URL, the number after the folder path. | | `recordId` | `number` | Yes | The record id, which is the \_ragicId value. | **Output** | Name | Type | Required | Description | | - | - | - | - | | `status` | `string \| null` | No | SUCCESS on success. | | `code` | `number \| null` | No | — | *** ### unlock `records.unlock` Unlock a record that was locked **Risk:** `write` ```ts theme={null} await corsair.ragic.api.records.unlock({ account: 'demo', path: '/sales', sheetIndex: 1, recordId: 102 }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `account` | `string` | Yes | The account name from your Ragic URL, such as "demo" in [www.ragic.com/demo/sales](http://www.ragic.com/demo/sales). | | `path` | `string` | Yes | The folder path from your URL, starting with a slash, such as /sales. | | `sheetIndex` | `number` | Yes | The sheet number from your URL, the number after the folder path. | | `recordId` | `number` | Yes | The record id, which is the \_ragicId value. | **Output** | Name | Type | Required | Description | | - | - | - | - | | `status` | `string \| null` | No | SUCCESS on success. | | `code` | `number \| null` | No | — | *** ### update `records.update` Update only the fields you send on one record, edit a subtable row by its row id, or delete one with *DELSUB* **Risk:** `write` ```ts theme={null} await corsair.ragic.api.records.update({ account: 'demo', path: '/sales', sheetIndex: 1, recordId: 3, fields: { '_subtable_2000154': { '29': { '2000147': 'Ms. Amy Tsai' } } }, checkLock: true }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `account` | `string` | Yes | The account name from your Ragic URL, such as "demo" in [www.ragic.com/demo/sales](http://www.ragic.com/demo/sales). | | `path` | `string` | Yes | The folder path from your URL, starting with a slash, such as /sales. | | `sheetIndex` | `number` | Yes | The sheet number from your URL, the number after the folder path. | | `fields` | `Record` | Yes | Field ID to value, only for the fields to change. A multi-select takes an array; a date needs yyyy/MM/dd or yyyy/MM/dd HH:mm:ss. A subtable is `_subtable_` keyed by row id: an existing row’s positive id (read from the record) edits that row, a negative id adds a new row. `_DELSUB_` with an array of row ids deletes those rows. | | `doFormula` | `boolean` | No | Recalculate every formula before saving. | | `doDefaultValue` | `boolean` | No | Load every default value before saving. | | `doLinkLoad` | `boolean \| first` | No | Run link and load operations: true after the formula recalculation, "first" before it. Either way doFormula must also be set when a recalculation is needed. | | `doWorkflow` | `boolean` | No | False skips the workflow scripts, which otherwise run. | | `doAIAgent` | `boolean` | No | False skips the AI Agents, which otherwise run. | | `notification` | `boolean` | No | Defaults to true: the save sends notifications. | | `doValidation` | `boolean` | No | Run the sheet’s field validation rules first. A failing field rejects the save. | | `checkLock` | `boolean` | No | Refuse the update when the record is locked. Without it Ragic ignores the lock and saves the update. | | `recordId` | `number` | Yes | The record id, which is the \_ragicId value. | **Output** | Name | Type | Required | Description | | - | - | - | - | | `status` | `string \| null` | No | SUCCESS when the record was saved. | | `msg` | `string \| null` | No | — | | `ragicId` | `number \| null` | No | The record id (\_ragicId). | | `rv` | `any` | No | — | | `data` | `Record \| null` | No | The saved record, keyed by field ID, with its reserved keys. | *** ## Schema ### get `schema.get` Read a sheet's field schema, including field IDs, types and subtables, so a write can be built without guessing. Needs an account manager's API key **Risk:** `read` ```ts theme={null} await corsair.ragic.api.schema.get({ account: 'demo', path: '/sales', sheetIndex: 1 }); ``` **Input** | Name | Type | Required | Description | | - | - | - | - | | `account` | `string` | Yes | The account name from your Ragic URL, such as "demo" in [www.ragic.com/demo/sales](http://www.ragic.com/demo/sales). | | `path` | `string` | Yes | The folder path from your URL, starting with a slash, such as /sales. | | `sheetIndex` | `number` | Yes | The sheet number from your URL, the number after the folder path. | **Output** | Name | Type | Required | Description | | - | - | - | - | | `sheet` | `object \| null` | No | — | | `fields` | `object[] \| null` | No | — | | `subtables` | `object[] \| null` | No | — | > [accordion] sheet full type > > ```ts theme={null} > { > sheetPath?: string | null, > sheetIndex?: number | string | null, > sheetName?: string | null, > keyFieldId?: number | string | null > } | null > ``` > [accordion] fields full type > > ```ts theme={null} > { > fieldId?: number | string | null, > fieldName?: string | null, > type?: string | null, > required?: boolean | null, > readOnly?: boolean | null, > computed?: boolean | null, > hidden?: boolean | null, > selectionOptionsPreview?: string[] | null > }[] | null > ``` > [accordion] subtables full type > > ```ts theme={null} > { > subtableKey?: number | string | null, > fields?: { > fieldId?: number | string | null, > fieldName?: string | null, > type?: string | null, > required?: boolean | null, > readOnly?: boolean | null, > computed?: boolean | null, > hidden?: boolean | null, > selectionOptionsPreview?: string[] | null > }[] | null > }[] | null > ``` *** This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.