Tool Reference

Get usage

Shows which subscription the key belongs to, what the key may do, today’s usage, and how much of the shared budget is available right now. Limits are shared by all the subscription’s keys.

List modules

Lists every module and whether it is enabled. A disabled module’s record types and tools are unavailable. Modules are turned on in the app’s settings, not through the assistant.

List countries

Lists the countries that country fields accept, with their ISO codes and names.

List subdivisions

Lists the states, provinces or regions of one country, with their ISO codes, names and types.

List legal forms

Lists the legal form codes valid for a jurisdiction, with names, for use when writing a legal form field. National forms appear alongside local ones.

Semantic search

Searches records and their metadata by meaning and returns the best matches, ranked. Files are not searched, and the results are a shortlist. Falls back to keywords if matching by meaning is cut short.

Search documents

Searches the text inside uploaded PDF, Word, RTF, text, HTML and CSV files and returns the best matches with a snippet. It does not cover images or scanned files. Results are a ranked shortlist.

List record types

Lists the record types the key can read, covering enabled modules plus always-on reference types. Each comes with a link pattern for opening a record in the app. This is where the assistant starts.

Describe record type

Describes one record type: its fields, custom fields and states, and which fields can be filtered, written or are required.

Query records

Finds records of one record type, with optional filters, one page at a time. Records come back in the record type’s fixed order. Live records only, never the trash.

Get record

Reads one record by its ID. It reports an error if the record doesn’t exist or the key can’t see it.

Create record

Creates one record of a record type. Required fields must be filled, and the new record is returned as a read would show it.

Update record

Changes selected fields on one live record. Fields left out stay as they are, and a field can be cleared.

Move record to trash

Moves one record to the trash. This can be undone with Restore record from trash.

Restore record from trash

Brings a trashed record back.

Permanently delete record

Permanently deletes one trashed record and everything attached to it. This cannot be undone, and it is refused while live records still refer to the record.

Batch write records

Applies up to 25 writes on one record type as a single transaction, all or nothing. Creates, updates, trashes, restores and purges can be mixed. Each item counts against the write budget.

List related resources

Lists the kinds of item that attach to records: attachments, events, workflows, workflow files, workflow events and timeline entries. Each comes with its filters and how it relates to the others.

Describe related resource

Describes the fields of one related resource, such as attachments, workflow events or the timeline.

Query attachments

Finds the files and links attached to records. Filter by the record they belong to or by date, and read the trash as a separate view. Files attached to workflows are listed separately.

Get attachment

Reads one attachment and the files and links inside it.

Upload attachment

Creates an attachment on a live record and uploads its files, or stores web addresses and file paths as links. Plan storage limits apply, and each file must fit the assistant’s per-call size limit.

Add attachment files

Adds more files to an existing attachment. Each file must fit the assistant’s per-call size limit.

Add attachment links

Adds links to an existing attachment: a web address, or a file-server path that is shown as written and never opened. A link already on the attachment is refused.

Update attachment

Changes an attachment’s name or description.

Move attachment to trash

Moves one attachment to the trash. This can be undone.

Restore attachment from trash

Brings a trashed attachment back.

Permanently delete attachment

Permanently deletes one trashed attachment and its files. This cannot be undone.

Batch write attachments

Applies up to 25 attachment changes as a single transaction, all or nothing. Updates, trashes, restores and purges are allowed. Uploads are done one at a time.

Download file

Gives a short-lived link, valid for about 60 seconds, for downloading one file. Links and file paths have no file to download.

Read file text

Reads the text of one file a page at a time, in order, without downloading it. It works only while the file’s text is available, and it is not available for images or scanned files.

Query events

Finds calendar events attached to records, such as deadlines, meetings and renewals. Filter by record or by date window, and read the trash as a separate view. Events created by workflows are listed separately.

Get event

Reads one calendar event.

Create event

Creates a calendar event on a live record, with a title, start and end, and optional reminders, recurrence and recipients.

Update event

Changes selected details of one live event. The record it belongs to cannot change.

Move event to trash

Moves one event to the trash. This can be undone.

Restore event from trash

Brings a trashed event back.

Permanently delete event

Permanently deletes one trashed event and everything attached to it. This cannot be undone.

Batch write events

Applies up to 25 event changes as a single transaction, all or nothing, working the same way as Batch write records.

List timeline

Lists the timeline entries of one record, which are its dated lifecycle states. A record must be named, so entries cannot be listed across records.

Get timeline entry

Reads one timeline entry.

Create timeline entry

Adds a manual timeline entry to a record, with a state, an effective date and an optional description. Entries the app derives automatically cannot be written.

Update timeline entry

Changes a manual entry’s state, date or description.

Delete timeline entry

Permanently deletes one manual timeline entry. Entries have no trash, so this cannot be undone.

Batch write timeline entries

Applies up to 25 manual entry changes as a single transaction, all or nothing. Creates, updates and deletes are allowed.

List workflow templates

Lists the workflow templates the key may launch, meaning those an admin has opened to integrations in enabled modules. It shows where each runs and its default due date, participants and checklist size.

Get workflow template

Reads one launchable workflow template. A template that isn’t open to integrations is not found.

Launch workflow

Starts a workflow from a template, with optional overrides for name, description, due date and participants. Participants are notified. A template with no default participants needs them named.

Query workflows

Finds workflows by the record they belong to, by status or by date. The trash is a separate view. Detail such as checklist items comes from Get workflow.

Get workflow

Reads one workflow with its checklist items, assignments and latest activity. Its files and events are listed separately.

Update workflow

Changes a workflow’s name, description or due date. Moving the due date notifies participants. Checklist items, assignments and status belong to the people working the workflow and cannot be changed.

Move workflow to trash

Moves one workflow to the trash. This can be undone. Participants are notified and the workflow’s events stop sending reminders.

Restore workflow from trash

Brings a trashed workflow back.

Permanently delete workflow

Permanently deletes one trashed workflow with its files, events and timeline entries. This cannot be undone.

Batch write workflows

Applies up to 25 workflow changes as a single transaction, all or nothing, working the same way as Batch write records. A create item is a launch.

Query workflow attachments

Finds files attached to workflows, such as outcome documents. Filter by workflow or by the record it concerns. Files attached directly to records are listed separately.

Get workflow attachment

Reads one workflow attachment and the files and links inside it.

Download workflow file

Gives a short-lived link, valid for about 60 seconds, for downloading one workflow file. Links and file paths have no file to download.

Query workflow events

Finds the calendar events workflows create, such as workflow and checklist due dates. Filter by workflow, record or date window. Events attached directly to records are listed separately.

Get workflow event

Reads one workflow-created calendar event.

Query reports

Lists saved report definitions, newest first, with the record type each draws on and its columns. Needs the Reporting plan feature.

Get report

Reads one report definition, with a link to the report’s page in the app for you to open.

Describe reports

Describes the fields and column types a report definition can use.

Run report

Runs a report and returns one page of rows with a description of each column. The result is data the assistant can turn into a spreadsheet. Saved grid filters don’t apply.

Create report

Creates a saved report on a record type. If no columns are given, it starts with the columns the app uses for that record type.

Update report

Changes a report’s name, columns or grid settings. The record type it draws on cannot change; create a new report instead.

Move report to trash

Moves one report to the trash. This can be undone.

Restore report from trash

Brings a trashed report back.

Permanently delete report

Permanently deletes one trashed report. This cannot be undone.

Batch write reports

Applies up to 25 report changes as a single transaction, all or nothing, working the same way as Batch write records.

Query charts

Lists saved ownership charts, newest first, with each one’s last render summary. Needs the Charts plan feature and the Entity Ownership module.

Get chart

Reads one chart, with a link to its page in the app. Exporting there gives PNG, JPG, PDF or print output with fonts included.

Describe charts

Describes the fields a chart’s definition and members can have.

Get chart layout

Reads the chart’s picture as last regenerated: an SVG plus the chart file. The SVG omits its font, so use the chart’s app page for a file with fonts. Fails until the chart is regenerated.

Get chart drift

Shows what has changed in your records since the chart was last regenerated: changed values, added cards and removed members. Regenerate the chart to apply the changes.

List chart versions

Lists a chart’s recent version history, newest first.

Get chart version

Reads one earlier version of a chart, with its membership and document as they stood then.

Create chart

Creates an ownership chart from a starting entity and rules. The chart is stored without a picture until it is regenerated.

Update chart

Changes a chart’s name, rules or members. Changes show only after the next regenerate, because nothing is rendered here.

Regenerate chart

Renders the chart from its saved rules and members. Only one chart can render at a time per subscription. The picture is then read with Get chart layout.

Move chart to trash

Moves one chart to the trash. This can be undone.

Restore chart from trash

Brings a trashed chart back.

Permanently delete chart

Permanently deletes one trashed chart with its picture and version history. This cannot be undone.

Batch write charts

Applies up to 25 chart changes as a single transaction, all or nothing, working the same way as Batch write records. None of them renders a picture.

Describe configuration

Reads the whole setup of the subscription in one step: record types with their custom fields and sections, option lists, timeline states and triggers, and event and workflow templates. The assistant reads this first.

List configuration kinds

Lists the kinds of configuration, such as fields, sections and templates, and where each lives.

Describe configuration kind

Describes the fields of one kind of configuration and the shape of its rules.

List configured record types

Lists the record types whose setup the key can read, each with its counts, last change and names of fields deleted for good.

Get configured record type

Reads the setup of one record type.

Set record type layout

Reorders a record type’s sections and fields in one step. The layout must list every section and every custom field, and a partial or outdated layout is refused.

List fields

Lists a record type’s custom fields in display order, with each one’s type, section, options and, for calculated fields, the rule behind them. Built-in fields appear under Describe record type.

Get field

Reads one custom field.

Create field

Adds a custom field to a record type, including select options and, for a calculated field, its rule. Existing records recalculate within minutes. Names that are reserved, in use or retired are refused.

Update field

Changes a custom field’s label, section, options, default or calculation rule. An option in use can’t be removed, the field’s type and name can’t change, and a manual field can’t become calculated.

Delete field

Permanently deletes a custom field. There is no trash, and its name is retired for good. It is refused while records or automations still use it.

Batch write fields

Applies up to 25 field changes on one record type as a single transaction, all or nothing. Deletes are final.

List sections

Lists a record type’s sections in order, with the fields in each. Fields in no section sit in an ungrouped area.

Get section

Reads one section.

Create section

Adds a section to a record type. Its name must be unique on that record type, and it sits above the ungrouped fields.

Update section

Renames a section or replaces its description.

Delete section

Deletes a section. Its fields move to ungrouped and nothing else changes. There is no trash, so this cannot be undone.

Batch write sections

Applies up to 25 section changes on one record type as a single transaction, all or nothing.

List option lists

Lists the built-in select fields of a record type whose choices your subscription can configure, with the current choices.

Get option list

Reads the choices of one configurable select field.

Update option list

Replaces the choices of a configurable select field with a new list in display order. A choice that a record uses, or that an automation names, can’t be removed or renamed.

Batch write option lists

Applies up to 25 option list replacements on one record type as a single transaction, all or nothing.

Get timeline states

Reads a record type’s timeline states and the rules that generate entries. Not found if the record type has no timeline.

Create timeline states

Turns on a record type’s timeline with an ordered set of states and optional rules that generate entries. Existing records pick up entries within minutes. Refused if a timeline already exists.

Update timeline states

Replaces a record type’s timeline states and, optionally, its generating rules. A state that entries use can’t be removed. Rules left out of a new list are removed along with their entries.

Delete timeline states

Removes a record type’s timeline setup. Final, with no trash, and refused while any timeline entry exists.

List event templates

Lists every calendar event template in enabled modules, with its record type, date rule, recurrence, reminders, recipients and triggers.

Get event template

Reads one calendar event template.

Create event template

Creates a calendar event template with a date rule, recurrence, reminders, recipients and triggers. An automatic trigger needs a date rule, and reminders need recipients.

Update event template

Changes a calendar event template. A list you send replaces the stored list, and the record type can’t change. The whole template is checked as the app’s settings would check it.

Delete event template

Permanently deletes a calendar event template. There is no trash. Events already created keep their dates.

Batch write event templates

Applies calendar event template changes as a single transaction, all or nothing. Deletes are final.

List configured workflow templates

Lists every workflow template in enabled modules as the app’s settings show it, whether or not it can be launched by integrations. Includes checklist items, documents, participants and triggers.

Get configured workflow template

Reads the setup of one workflow template.

Create workflow template

Creates a workflow template with its checklist, documents, participants, launch rules and triggers. Document files are uploaded in the app. The record type can’t change later.

Update workflow template

Changes a workflow template. Lists you send replace the stored lists, and documents can’t change while any document has files. The record type can’t change.

Delete workflow template

Permanently deletes a workflow template. There is no trash. Workflows already launched from it stay.

Batch write workflow templates

Applies workflow template changes as a single transaction, all or nothing. Deletes are final.