====== Collection API Reference ======

All requests go to ''https://yourdomain.com/api/apic.php'' via **POST only** (GET always returns error -5).
See [[developer:authentication|Authentication]] for required auth parameters.

Every call requires: ''u'' (user ID), ''k'' (API key), ''r'' (collection ref), ''g'' (GX group), ''f'' (function).

===== Response Envelope =====

<code json>
{
  "error":    "0",
  "fn":       "readone",
  "version":  "1.0",
  "datetime": "2026-05-18 10:00:00",
  "fields":   "5",
  "data": { "fnerr": 0 }
}
</code>

''"error": "0"'' means the request reached the function. Check ''data.fnerr'' for function-level results.

===== Reading =====

^ Function ^ Purpose ^ Key params ^
| ''crosslist'' | Browse or filter records | ''dxField'' + ''dxValue'', or ''filter'' JSON |
| ''readone'' | Get one record by ID | ''dxId'' required |
| ''search'' | Full-text keyword search | ''q={keyword}'' |
| ''count'' | Count matching records | ''filter'' JSON optional |
| ''readlist'' | Distinct values of one column | ''dxField'' required |
| ''export'' | Like crosslist with field header; supports CSV | ''format=csv'' or ''format=json'' |
| ''myrecords'' | Records owned by authenticated user | none |
| ''listarchived'' | Soft-deleted records | none |

===== Writing =====

^ Function ^ Purpose ^ Key params ^
| ''create'' | Create a new record | field columns + optional ''notes'' |
| ''update'' | Update a record (partial — omitted fields unchanged) | ''dxId'' + field columns |
| ''transition'' | Execute a workflow action | ''dxId'' + ''actionId'' |
| ''bulkcreate'' | Create multiple records in one call | JSON array of record objects |
| ''bulkupdate'' | Update multiple records in one call | JSON array of ''{dxId, fields}'' objects |
| ''duplicaterecord'' | Clone an existing record | ''dxId'' required |
| ''archiverecord'' | Soft-delete a record (reversible) | ''dxId'' required |
| ''restorerecord'' | Restore an archived record | ''dxId'' required |
| ''gdprwipe'' | Permanently wipe PII from a record | ''dxId'' required; irreversible |
| ''transferownership'' | Reassign ownership | ''dxId'' + ''intLogin_Id'' |
| ''allocaterecord'' | RLS-aware assignment | ''dxId'' + ''intLogin_Id'' |

===== Interactions (Audit Trail / Notes) =====

^ Function ^ Purpose ^ Key params ^
| ''interactionlist'' | Full audit trail for a record | ''dxId'' required |
| ''addinteraction'' | Add a note | ''dxId'' + ''notes'' |
| ''readinteraction'' | Read a specific interaction | ''ixId'' required |
| ''updateinteraction'' | Edit an interaction note | ''ixId'' + ''notes'' |
| ''deleteinteraction'' | Remove an interaction | ''ixId'' required |

===== Transitions =====

^ Function ^ Purpose ^ Key params ^
| ''transitions'' | List valid workflow actions for a record | ''dxId'' optional |
| ''transition'' | Execute a workflow action | ''dxId'' + ''actionId'' |

**Important:** Pass ''actionId'' (not ''intAction_Id''). When completing a record, pass ''strD5_1_5=True'' explicitly.

===== Webhooks =====

^ Function ^ Purpose ^ Key params ^
| ''webhook'' | Register a new webhook | ''url'' + ''event'' (create/update/delete) |
| ''webhooks'' | List all registered webhooks | none |
| ''deletewebhook'' | Remove a webhook | ''webhookId'' required |

Webhooks fire on create, update, or delete events. The payload mirrors the record's field values at event time.

===== Bulk & Bootstrap Operations =====

^ Function ^ Purpose ^ Key params ^
| ''bulkcreate'' | Create multiple records in one call | JSON array |
| ''bulkupdate'' | Update multiple records | JSON array of ''{dxId, fields}'' |
| ''bootstrap'' | Initialise a collection from a template | ''templateId'' |
| ''applytemplate'' | Apply a template to an existing collection | ''templateId'' |

===== Swimlane Groups =====

^ Function ^ Purpose ^ Key params ^
| ''createitemgroup'' | Create a swimlane group | ''name'' required |
| ''listitemgroups'' | List all swimlane groups | none |
| ''updateitemgroup'' | Rename or reorder a group | ''groupId'' + fields |
| ''deleteitemgroup'' | Delete a group (records stay) | ''groupId'' required |
| ''movetogroup'' | Move a record into a group | ''dxId'' + ''groupId'' |

===== Row-Level Security (RLS) =====

^ Function ^ Purpose ^ Key params ^
| ''enablerls'' | Enable RLS on a collection | ''mode'' (Owner / Custom / None) |
| ''setrls'' | Set RLS permissions for a record | ''dxId'' + user/group params |
| ''getrls'' | Get current RLS settings | ''dxId'' required |

Use **Owner** mode so each record is only visible to its creator. Use **Custom** for per-user or per-group access grants.

===== Record Linking =====

^ Function ^ Purpose ^ Key params ^
| ''linkrecords'' | Link two records | ''dxId'' + ''dxId2'' + optional ''notes'' |
| ''unlink'' | Remove a link | ''dxId'' + ''dxId2'' |
| ''getlinks'' | Get all linked records | ''dxId'' required |

===== Filtering =====

==== Simple ====
<code>
dxField=strD5_1_25&dxValue=High
</code>

==== Advanced (multi-condition JSON) ====
<code json>
[
  {"field": "strD5_1_25", "op": "eq",   "value": "High"},
  {"field": "strD5_1_6",  "op": "like", "value": "Dev"}
]
</code>

Operators: ''eq'', ''neq'', ''like'', ''gt'', ''lt'', ''in'', ''notin'', ''empty''

===== Pagination =====

Works on ''crosslist'', ''search'', ''export'':

  * Offset-based: ''page=N&per_page=N'' — response includes ''total'', ''pages'', ''page'', ''per_page''
  * Cursor-based: ''cursor={next_cursor}'' from previous response
  * Max ''per_page'': 500 for crosslist/search, 1000 for export

===== Schema Inspection =====

^ Function ^ Purpose ^
| ''describe'' | Field schema — columns, types, options |
| ''meta'' | Full schema — fields, views, actions, functions |
| ''fieldlist'' | Raw FX field definitions |
| ''actionlist'' | Available actions |

===== Analytics =====

^ Function ^ Purpose ^ Key params ^
| ''aggregate'' | Count/sum/groupby across a group | ''groupBy'', ''agg'' params |