onx-skill/references/record-payloads.md

Onspring Record Payloads & API Data Types Reference

This reference describes the exact JSON structures, data formats, and filter syntax used with onx records save, onx records query, onx records batch-get, and onx records batch-delete, grounded in the Onspring API v2 Specification.

records save Payload

Used for creating or updating records:

onx records save --json '<JSON_STRING>'
# or
onx records save --file ./record.json
# or
cat ./record.json | onx records save --stdin

JSON Structure

{
  "appId": 195,
  "recordId": null,
  "fields": {
    "6983": "A New Test Task",
    "6984": "<p>This is a test task.</p>",
    "6985": "2026-10-01T06:00:00Z",
    "6986": "4118d53a-9121-4345-8682-07f23d606daa",
    "6987": [4],
    "6988": 100.5
  }
}

Input Fields Specification

Property	Type	Description
appId	number	The ID of the app that contains or will contain the record (required).
recordId	number | null	The ID of the record to update. If null or omitted, a new record is created.
fields	object	Key-value mapping where each key is the string representation of a Field ID, and the value is formatted per the field's data type.

Field Value Types When Saving

• Text / Multi-line Text: string (e.g., "Title" or HTML "<p>Description</p>").
• Number / Currency: number (e.g., 42, 100.50).
• Date / Time: string in UTC ISO 8601 format (e.g., "2026-10-01T12:00:00Z"). Dates are always passed back and forth in UTC.
• List (Single-Select): string containing the GUID of the chosen list value (e.g., "4118d53a-9121-4345-8682-07f23d606daa").
• List (Multi-Select): Array of GUID strings string[] (e.g., ["4118d53a-...", "1c1c5f7e-..."]).
• Reference (Single-Select): Array with one integer record ID [140] or integer 140.
• Reference (Multi-Select): Array of integer record IDs (e.g., [140, 141]).
• Attachment / File: Uploaded separately via onx files upload.

Output on Success (onx records save)

{
  "id": 140,
  "warnings": []
}

records query Payload & Filter Syntax

Used for filtering and querying records across an app:

onx records query --json '<JSON_STRING>'

JSON Structure

{
  "appId": 195,
  "filter": "6983 eq 'Test Task' and 6987 gt 50",
  "fieldIds": [6983, 6986, 6987],
  "dataFormat": "Formatted"
}

Request Fields

Property	Type	Description
appId	number	App ID containing the records (required).
filter	string	Filter expression referencing Field IDs (required).
fieldIds	number[]	Optional array of field IDs to include in the response. If omitted, all fields are returned.
dataFormat	string	Optional: "Raw" or "Formatted" (defaults to "Raw").

Query Filter Operators & Rules

Filter expressions evaluate field values using Field IDs as identifiers.

Operator	Description	Applicable Field Types
eq	Equals	Text, Number, Date, Auto-Number, Formulas (text/number/date)
ne	Not equals	Text, Number, Date, Auto-Number, Formulas (text/number/date)
lt	Less than	Number, Date, Auto-Number, Formulas (number/date)
gt	Greater than	Number, Date, Auto-Number, Formulas (number/date)
contains	List contains item (by name or GUID)	List fields, List formulas
isnull	Field has no value	Text, Number, Date, Auto-Number, Formulas
notnull	Field has a value	Text, Number, Date, Auto-Number, Formulas

Literal Delimiters

• String values: Must be enclosed in single quotes ' (e.g., 6983 eq 'Active').
• Date values: Must be enclosed in single quotes ' preceded by datetime (e.g., 6985 gt datetime'2026-01-01T00:00:00Z').
• Logical combination: Combine with and, or, and negate with not. Group expressions using parentheses ( ... ).

Example:

(6983 eq 'Active' or 6983 eq 'Pending') and 6987 gt 100 and 6985 notnull

records batch-get Payload

Used to fetch specific records in bulk (maximum 100 records per request):

onx records batch-get --json '{
  "appId": 195,
  "recordIds": [1, 2, 3],
  "fieldIds": [6983, 6986],
  "dataFormat": "Formatted"
}'

Output:

{
  "count": 3,
  "items": [
    {
      "appId": 195,
      "recordId": 1,
      "fieldData": [
        {
          "type": "String",
          "fieldId": 6983,
          "value": "Task 1"
        }
      ]
    }
  ]
}

records batch-delete Payload

Used to delete records in bulk (maximum 100 records per request):

onx records batch-delete --json '{
  "appId": 195,
  "recordIds": [138, 139]
}'

Output on success:

{
  "ok": true
}

Understanding dataFormat: Raw vs Formatted

When retrieving records (list, get, batch-get, query) or reports, dataFormat controls the output format:

Field Type	Raw Format	Formatted Format
AutoNumber	number (e.g. 1)	Formatted string (e.g. "APP-001")
Date/Time	ISO 8601 UTC string (e.g. "2026-10-01T06:00:00Z")	Display string with user formatting (e.g. "10/1/2026 6:00 AM")
List	Value GUID string(s)	Value name string(s) (e.g. "In Progress")
Number / Currency	number (e.g. 100.5)	Display string with symbol (e.g. "$100.50")
Text	HTML string (e.g. "<p>Sample</p>")	Plain string with HTML stripped (e.g. "Sample")
TimeSpan	Object { "quantity": 10, "increment": "Minutes", "recurrence": "None" }	Display string (e.g. "10 Minutes")

Record ID vs Display Field

Important

The recordId used in onx CLI commands (--record <ID>) and API routes is the integer system record ID (e.g., 140). Do not confuse this with the text value formatted by an AutoNumber or Display field in the Onspring GUI (e.g., "INC-1002").