Skip to main content

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.

OperationMethodPath after the base
Query with URL parametersGET/{datasetId}
Query with JSON parametersPOST/{datasetId}
Insert one recordPOST/{datasetId}/records
Update all granted writable fieldsPUT/{datasetId}
Update selected granted fieldsPATCH/{datasetId}
Delete one recordDELETE/{datasetId}
Read authorized dataset metadataGET/_schema
Read one dataset's metadataGET/_schema/{datasetId}
Read the role-specific OpenAPI documentGET/_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​

ParameterMeaning
fieldsAuthorized full field paths; comma-separated in GET, an array in POST. Omit to return all role-authorized fields, up to 4096
filterFilter expression or JSON in GET; a structured condition object in POST
order / sortGET uses order=account.name asc; POST uses sort: [{field, direction}]. Up to five sorting fields
limitRows per page, 1–200; default 50
cursorCursor returned by the preceding page
directionforward for the next page, backward for the previous page
timeoutMsQuery timeout, 1000–15000 milliseconds; default 8000
includeColumnsInclude 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 statusTypical reasonAction
400Invalid fields, body, filter, or cursorCheck the generated contract and submitted values
401Invalid, expired, disabled, or rotated keyCheck the key and its current status
403Missing grant, row-scope failure, disabled role/service, or access changed during executionCheck role bindings, scope, and database privileges
404Missing resource or record; write target outside scopeConfirm the resource/key and scope
405Method unsupported on the pathUse the documented method/path pair
409Structure, cursor, constraint, or authorization conflictInspect the log, repair the configuration if necessary, then restart the request
413 / 415Body too large or wrong content typeReduce the JSON body or use application/json
429Key rate limit or tenant query capacity reachedRespect Retry-After and reduce concurrency
502 / 504Source query/connection failure or timeoutCheck the original error, database, and timeout
503Write commit outcome unknownVerify 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.