HTTP API Requests and Errors
Use the address generated in the API service's Documentation and testing panel. Examples below use service code erp; replace the host, dataset ID, field paths, and values with those generated for your service.
Routes And Methods
The common base path is /api/data/erp.
| Operation | Method | Path after the base |
|---|---|---|
| Query with URL parameters | GET | /{datasetId} |
| Query with JSON parameters | POST | /{datasetId} |
| Insert one record | POST | /{datasetId}/records |
| Update all granted writable fields | PUT | /{datasetId} |
| Update selected granted fields | PATCH | /{datasetId} |
| Delete one record | DELETE | /{datasetId} |
| Read authorized dataset metadata | GET | /_schema |
| Read one dataset's metadata | GET | /_schema/{datasetId} |
| Read the role-specific OpenAPI document | GET | /_openapi |
A method and path together identify the operation. GET and POST queries share a resource URL; the POST query accepts complex JSON without putting it in the URL. Insert uses /records to distinguish it from a POST query. Updates and deletes identify the complete record key in their JSON body, supporting composite keys.
Headers
Send X-API-Key on every request. For JSON bodies, send Content-Type: application/json.
export SOLN_API_KEY='replace-with-your-key'
curl 'https://runtime.example/api/data/erp/DATASET_ID?limit=20' \
-H "X-API-Key: $SOLN_API_KEY"
Query Parameters
| Parameter | Meaning |
|---|---|
fields | Authorized full field paths; comma-separated in GET, an array in POST. Omit to return all role-authorized fields, up to 4096 |
filter | Filter expression or JSON in GET; a structured condition object in POST |
order / sort | GET uses order=account.name asc; POST uses sort: [{field, direction}]. Up to five sorting fields |
limit | Rows per page, 1–200; default 50 |
cursor | Cursor returned by the preceding page |
direction | forward for the next page, backward for the previous page |
timeoutMs | Query timeout, 1000–15000 milliseconds; default 8000 |
includeColumns | Include authorized field definitions in meta.columns; default false |
curl -X POST 'https://runtime.example/api/data/erp/DATASET_ID' \
-H "X-API-Key: $SOLN_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"fields":["account.name"],"filter":{"field":"account.active","op":"eq","value":true},"sort":[{"field":"account.name","direction":"asc"}],"limit":20}'
POST queries use a JSON body without URL query parameters. Do not submit SQL, credentials, service/role overrides, or a replacement data source in the body.
Filter operators include eq, ne, gt, gte, lt, lte, in, notIn, contains, notContains, startsWith, endsWith, isNull, and isNotNull. Combine conditions using logic: "and" or logic: "or" with a conditions array. Filters allow up to five nested groups and 50 leaf conditions.
Pagination
Pass meta.nextCursor as cursor for the next page. Pass meta.previousCursor with direction=backward for the previous page. Keep fields, filters, sorting, and limit unchanged.
Each traversal allows up to 10,000 rows. When traversalLimitReached is true, narrow the filter and start a new traversal. Pages read live source data; they are not a frozen multi-request data snapshot.
Dataset or authorization changes can invalidate an existing cursor. Start again without the old cursor after handling the change. Page responses are bounded to 4 MiB, with up to 16,384 characters per cell.
Field Paths And Returned Values
Field selectors use source-qualified paths such as account.name. The response nests those values under the form API name, or under the table name for a physical table.
{
"resource": [
{
"account": {
"name": "Example customer",
"credit": "500000.0000000000",
"owner": {"_value": "MEMBER_ID", "name": "Alex"}
},
"computed": {"score": "12"}
}
],
"meta": {"hasMore": false, "nextCursor": null, "limit": 20}
}
Joined forms nest under their association field codes when available. _value preserves an authorized reference or JSON/XML parent value alongside its selected children. Use the generated schema for your exact paths; they are not always the same as the dataset's internal t0/t1 aliases.
Numeric database fields and numeric scalar subfields are returned as strings to preserve precision. Booleans are JSON booleans. JSON parent values are parsed as JSON values; XML parent values remain XML strings. Empty values are null, and invalid JSON parent values return null.
Single-Record Writes
An update body supplies key using every primary-key field, plus values for the fields to change:
{
"key": {"account.id": "RECORD_ID"},
"values": {"account.name": "Updated name"}
}
Use PATCH for a subset of granted writable fields. PUT requires every granted writable field. DELETE uses only key and must omit values.
An insert body contains values and is sent to /{datasetId}/records using POST. A successful insert returns HTTP 201 and its generated or supplied primary key. Other successful writes return HTTP 200 with the record key and affected-row count.
See write eligibility and grants before enabling these operations.
Error Responses
{"error":{"code":"DATA_CONNECT_API_STRUCTURE_CHANGED"},"requestId":"REQUEST_ID"}
| HTTP status | Typical reason | Action |
|---|---|---|
| 400 | Invalid fields, body, filter, or cursor | Check the generated contract and submitted values |
| 401 | Invalid, expired, disabled, or rotated key | Check the key and its current status |
| 403 | Missing grant, row-scope failure, disabled role/service, or access changed during execution | Check role bindings, scope, and database privileges |
| 404 | Missing resource or record; write target outside scope | Confirm the resource/key and scope |
| 405 | Method unsupported on the path | Use the documented method/path pair |
| 409 | Structure, cursor, constraint, or authorization conflict | Inspect the log, repair the configuration if necessary, then restart the request |
| 413 / 415 | Body too large or wrong content type | Reduce the JSON body or use application/json |
| 429 | Key rate limit or tenant query capacity reached | Respect Retry-After and reduce concurrency |
| 502 / 504 | Source query/connection failure or timeout | Check the original error, database, and timeout |
| 503 | Write commit outcome unknown | Verify the actual record before retrying |
A DATA_CONNECT_API_STRUCTURE_CHANGED error means the saved dataset and its current readable rule could not be used together. Check the original cause in Call logs → Details, then verify source structure, field paths, types, and any remaining filter. Ordinary supported dataset edits reconcile grants automatically, but an incompatible database change or invalid caller filter can still require correction.
Date values must be valid calendar dates in YYYY-MM-DD form. Datetime values also validate month/day, leap years, clock fields and any UTC offset; impossible dates or times are rejected before querying or writing the database.