The generated API
Every record type gets its own REST surface the moment you publish it - plus the schema endpoint to build typed clients against, and four access tiers.
What you get, and when
Publishing a schema version gives that record type its own REST URL space immediately. There is no code generation step and no redeploy — the routes are registered once and dispatched at runtime, so a newly published version is served straight away.
The shape is the same for every record type, which is the point: once you have integrated with one, you have integrated with all of them.
The URL space
Every operation hangs off a coordinate of record type, schema and version:
/v1/egav/portal/entity/{record_type}/attribute-set/{schema}/v{version}/flat/The same paths exist under four separately authenticated tiers — see Access tiers below. Within a coordinate:
| Method | Path | Does |
|---|---|---|
GET | /flat/ | List, with paging, filtering, sorting and search |
POST | /flat/ | Create one record |
GET | /flat/{id} | Read one record |
PUT | /flat/{id} | Update one record |
DELETE | /flat/{id} | Soft-delete one record |
POST PUT DELETE | /flat/bulk | Create, update or delete in bulk |
GET | /json-schema | The validation schema for this version |
GET | /ui-schema | How the fields should be presented |
On a schema with record history or draft publishing enabled, you also get /flat/{id}/versions, /flat/{id}/versions/{version_id}/restore, /flat/{id}/publish and /flat/{id}/published.
Listing
Lists take page, per_page, filters and sort. Free-text search is q, which does a multi-column match by default; pass use_fts=true to use the weighted, language-aware full-text index instead — worth it once a record type has real volume.
Describing the API to your tools
Two things are generated, and they answer different questions.
The service description — an OpenAPI document with browsable documentation — describes the service. Be aware of what it is not: the dynamic record routes appear in it once, as parameterised paths with generic object bodies. It will not give you a typed client per record type.
The schema endpoint is where per-record-type typing lives. GET .../json-schema returns the validation schema for that published version, and /ui-schema returns the presentation rules. This is the pair to build against — it is versioned with the model, so a client reading it cannot drift from the shape the server enforces.
If you are generating client types, generate them from the schema endpoint per version, not from the service description.
Access tiers
The same record paths are exposed under four tiers, each authenticated differently. Pick the narrowest one that does the job.
| Tier | Who it is for | Auth |
|---|---|---|
| Portal | Your signed-in users | The user's own session |
| Client | Another system you control | An API key you mint |
| Internal | Service-to-service inside the platform | A service key |
| Public | Anonymous readers, opt-in per schema | None |
Two behaviours worth knowing:
- API-key callers are always served the published version, never your working draft. You cannot accidentally expose in-progress work to an integration.
- Public access is reads only. Anonymous writes are refused outright, and the tier is off unless you opt a schema into it. It is available only for schemas that publish on save.
API keys
Mint, list, rotate, disable and revoke keys yourself. A key can be scoped to particular record types, and carries its own per-minute and per-hour request limits within your organization's overall budget.
Rotate rather than delete when handing over to a new integration — rotation gives you a window where both work.
Getting data in
Beyond the API, two routes exist for bulk work:
- Bulk endpoints —
POST/PUT/DELETE .../flat/bulk. Note that a bulk insert charges the whole batch against your row quota, so it cannot be used to slip past a limit. - Import and export — every published version is registered automatically for CSV and JSON import and export, with a sample file you can download to see the expected shape. Nobody has to wire this up per schema.
Files
Files upload directly to storage through a short-lived signed link, then get attached to a record field:
- Request a signed upload URL.
- Upload straight to storage.
- Confirm, then move the file onto the record field.
Signed links are also issued for download, preview and PDF viewing. Storage location can be resolved per organization.
Where to go next
- Getting changes out — subscribing your systems to record events.
- Connecting a system to a workflow — using these records inside a process.