meta data for this page
  •  

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
developer:api [2026/05/18 06:56] – [Collection API Reference] claudedeveloper:api [2026/06/02 06:46] (current) – Update: webhooks, bulk ops, swimlanes, RLS, full function reference claude
Line 1: Line 1:
 ====== Collection API Reference ====== ====== Collection API Reference ======
  
-All requests go to ''https://yourdomain.com/api/apic.php'' via POST or GET.+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. See [[developer:authentication|Authentication]] for required auth parameters.
  
-===== Response Envelope =====+Every call requires: ''u'' (user ID), ''k'' (API key), ''r'' (collection ref), ''g'' (GX group), ''f'' (function).
  
-All responses share this outer structure:+===== Response Envelope =====
  
 <code json> <code json>
Line 15: Line 15:
   "datetime": "2026-05-18 10:00:00",   "datetime": "2026-05-18 10:00:00",
   "fields":   "5",   "fields":   "5",
-  "data": { ... }+  "data": { "fnerr": 0 }
 } }
 </code> </code>
  
-''"error": "0"'' means the request reached the function. Function-level results and errors are inside ''data.fnerr''.+''"error": "0"'' means the request reached the function. Check ''data.fnerr'' for function-level results.
  
-===== Functions =====+===== Reading =====
  
-==== meta — Start here ====+^ 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 |
  
-Returns the complete collection schema in one call: every field, view, action, and available function. Always call this first when working with an unfamiliar collection.+===== Writing =====
  
-''f=meta&g={any_view_id}''+^ 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'' |
  
-Response ''data'': +===== Interactions (Audit Trail / Notes) =====
-^ Field ^ Contents ^ +
-| ''collection'' | Name and ref of the collection | +
-| ''fields[]'' | Every field: column, label, type, options | +
-| ''views[]'' | All active views: id and name | +
-| ''actions[]'' | All active actions: id, name, pre_fills | +
-| ''functions[]'' | All callable function names | +
-| ''usage'' | Template strings for every common operation |+
  
-==== describe ====+^ 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 |
  
-Returns field schema only — lighter than ''meta''.+===== Transitions =====
  
-''f=describe&g={view_id}''+^ Function ^ Purpose ^ Key params ^ 
 +| ''transitions'' | List valid workflow actions for a record | ''dxId'' optional | 
 +| ''transition'' | Execute a workflow action | ''dxId'' + ''actionId'' |
  
-==== readone ====+**Important:** Pass ''actionId'' (not ''intAction_Id''). When completing a record, pass ''strD5_1_5=True'' explicitly.
  
-Returns all field values for a single record.+===== Webhooks =====
  
-''f=readone&dxId={id}&g={view_id}''+^ 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 |
  
-==== readlist ====+Webhooks fire on create, update, or delete events. The payload mirrors the record's field values at event time.
  
-Returns all distinct values in a single column across visible records. Useful for filter dropdowns.+===== Bulk & Bootstrap Operations =====
  
-''f=readlist&dxField={column}&g={view_id}''+^ 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'' |
  
-==== crosslist ====+===== Swimlane Groups =====
  
-Returns all records where a column equals a value.+^ 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'' |
  
-''f=crosslist&dxField={column}&dxValue={value}&g={view_id}''+===== Row-Level Security (RLS) =====
  
-Optional: ''laneId={id}'' to filter to a swim lane. ''swimlane_layout=1'' to group by lane.+^ 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 |
  
-==== create ====+Use **Owner** mode so each record is only visible to its creator. Use **Custom** for per-user or per-group access grants.
  
-Creates a new record and logs a creation interaction.+===== Record Linking =====
  
-''f=create&g={write_view_id}'' + field columns as params+^ 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 |
  
-Response: ''{ "fnerr": 0, "dxid": 1234 }''+===== Filtering =====
  
-==== update ====+==== Simple ==== 
 +<code> 
 +dxField=strD5_1_25&dxValue=High 
 +</code>
  
-Updates an existing record. Only included fields are changed (partial update). +==== Advanced (multi-condition JSON) ==== 
- +<code json> 
-''f=update&dxId={id}&g={write_view_id}'' + fields to change +[ 
- +  {"field": "strD5_1_25", "op": "eq",   "value": "High"}, 
-==== interactionlist ==== +  {"field": "strD5_1_6",  "op": "like", "value": "Dev"} 
- +] 
-Returns the full audit trail for one record. +</code>
- +
-''f=interactionlist&dxId={id}&g={view_id}'' +
- +
-==== actionlist ==== +
- +
-Returns all active actions for this collection. +
- +
-''f=actionlist&g={view_id}'' +
- +
-==== gdprwipe ==== +
- +
-Anonymises all string field values in a record (replaces with ''****'') and logs the wipe. +
- +
-''f=gdprwipe&dxId={id}&g={write_view_id}'' +
- +
-==== addfield ==== +
- +
-Adds a new field to the collection. +
- +
-''f=addfield&fxLabel={label}&fxType={type}&fxOptions={opt1,opt2}&g={write_view_id}'' +
- +
-See [[developer:collections|Building Collections]] for field types. +
- +
-==== bulkcreate ==== +
- +
-Batch-creates up to 500 records from a JSON array.+
  
-''f=bulkcreate&records=[{"col1":"val1",...},...]&g={write_view_id}''+Operators: ''eq'', ''neq'', ''like'', ''gt'', ''lt'', ''in'', ''notin'', ''empty''
  
-Response: ''{ fnerr, total, created, failed, results:[...] }''+===== Pagination =====
  
-==== createcollection (admin) ====+Works on ''crosslist'', ''search'', ''export'':
  
-Provisions a new collection with FX/DX/IX/GX tables. Requires admin credentials.+  * 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
  
-''f=createcollection&collection_name={name}&collection_ref={ref}''+===== Schema Inspection =====
  
-Does not require ''r'' or ''g'' — auth params alone are sufficient.+^ Function ^ Purpose ^ 
 +| ''describe'' | Field schema — columns, types, options | 
 +| ''meta'' | Full schema — fields, views, actions, functions | 
 +| ''fieldlist'' | Raw FX field definitions | 
 +| ''actionlist'' | Available actions |
  
-===== Function-Level Error Codes =====+===== Analytics =====
  
-^ Code ^ Meaning ^ +^ Function ^ Purpose ^ Key params ^ 
-| ''0'' | Success | +| ''aggregate'' | Count/sum/groupby across a group | ''groupBy'', ''agg'' params |
-| ''1'' | Required parameter missing | +
-| ''2'' | Record not found | +
-| ''3'' | Field not in schema | +
-| ''5'' | DB insert failed | +
-| ''6'' | Invalid value for field type | +
-| ''7'' | Unknown tag | +
-| ''8'' | RLS denied (caller does not own this record) |+