Send readings with the Ingestion API

Use the Ingestion API when your own gateway, application, or vendor integration sends readings to SanSignal. The endpoint accepts a batch and returns processing run IDs.

Before you send data

Create a project Ingest API connection and key as described in API authentication. Confirm the destination project’s default site or obtain the specific destination site ID.

Choose stable instrument and variable names. When a new instrument is created through ingestion, an omitted or null site_id uses the project’s default site. For an existing instrument, submitting site_id does not move it to a different site.

Submit a first batch

Set SANSIGNAL_API_URL to your deployment’s API base URL and SANSIGNAL_INGEST_KEY to an ingestion key. Save the following example as readings.json, replacing the names, timestamp, and values with your data:

{
  "data": [
    {
      "instrument_timestamp": "2026-09-04T12:00:00Z",
      "instrument_name": "PZ-01",
      "ingested_variables": [
        { "name": "pressure", "value": 42.5 },
        { "name": "temperature", "value": 18.2 }
      ]
    }
  ]
}

Then submit the file. Choose an idempotency key unique to this logical batch:

curl "$SANSIGNAL_API_URL/v1/ingest" \
  --request POST \
  --header "Authorization: Bearer $SANSIGNAL_INGEST_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: pz01-20260904T120000Z-batch1" \
  --data-binary @readings.json

Use an RFC3339 timestamp with an explicit offset, such as Z for UTC. Fractional seconds are accepted; other valid offsets are normalized to UTC and produce a normalization warning. A local date and time without an offset is not accepted. Send decimal values as JSON numbers and use the exact names intended for your field channels.

Acceptance is not completion

A successful response contains a request ID and entries under data.runs, each with a run_id and state. HTTP 200 means the request was admitted; it does not mean the final readings or calculations have completed.

Keep the request and run IDs in your integration logs. Open the project’s Ingestion → Runs to inspect processing and validation. Confirm the final instrument, timestamp, and values in the dashboard before expanding to larger batches.

Retry the same logical batch

If the network response is uncertain, retry the same batch with the same Idempotency-Key and connection. A replay can return the previously admitted runs.

Never reuse an idempotency key for a different batch. The current implementation replays by connection and key without comparing the new request body with the original body. A changed body with the same key must not be expected to produce a conflict or a new ingestion.

Give new batches new keys and retain enough local information to retry an unchanged batch after a temporary failure.

Corrections and missing values

For an existing variable value at the same instrument timestamp, the default behavior leaves the existing value unchanged. Set allow_override: true on the submitted variable when you intend to correct it. Use a new batch idempotency key for that correction.

The per-variable remove: true operation removes an existing recorded value and requires the value field to be omitted. Removal is independent of allow_override and is distinct from submitting null. Review the API reference before implementing corrections so retries and intended deletion remain distinguishable.

A null or omitted value represents missing data for a known variable. An unknown variable submitted only with null is omitted until a typed, non-null value establishes its type; a point left with no ingestible values fails validation. Create the variable first if your initial readings can all be missing.

Optional nil_reason values come from a defined allowed set; do not invent reason strings. Blank strings and the numeric sentinel -999 are rejected, so normalize those source markers to the supported missing-data representation before submitting them.

view_options and expected_cadence_s are rejected by ingestion. Configure presentation and cadence through the dashboard or the supported Developer API variable-management operations.

Commission the sender

Test a normal numeric reading, a representative text or missing value if used, and a same-key retry. Verify the stored result and run state for each. For failures, inspect the response and run diagnostics, correct the cause, and follow Runs and troubleshooting.