Quickstart

Read your workspace records, then send one signed test event. You need the API key, workspace ID and signing secret RegEngine issues.

Request access

RegEngine issues API keys on request. There is no self-serve key creation. After you ask, RegEngine sends you three things:

An API key that starts with rge_live_.
Your workspace ID, a UUID. Calls infer the workspace from the key; the ID is only a query parameter on a few endpoints.
The signing secret RegEngine issues for ingest. You use it to sign the body of every ingest request.

Request developer access

Set your environment variables

Keep both values out of version control and out of client-side code. Anyone who holds the API key and the signing secret can send events into the workspace that key belongs to. If you think either value is exposed, tell RegEngine right away.

bash

export REGENGINE_API_KEY="rge_live_..."      # from RegEngine
export REGENGINE_SIGNING_SECRET="..."       # from RegEngine

Do not send an X-Tenant-ID header. RegEngine takes the workspace from your key, and a value that differs from it is refused with a 403.

Make a read call (writes nothing)

Start with a read to confirm the key works:

bash

curl -s "https://regengine.co/api/v1/records?limit=1" \
  -H "X-RegEngine-API-Key: $REGENGINE_API_KEY"

Expect a 200 with your workspace ID in tenant_id. A new workspace has no events yet:

json

{
  "tenant_id": "<your workspace ID>",
  "events": [],
  "total": 0
}

Send the key in X-RegEngine-API-Key. An Authorization header is not accepted. A 401 means the key is missing or not recognized; a 403 means the key lacks the records.read scope.

Send one signed test event (this writes)

Writes are permanent and can be billed

Accepted events are appended to your workspace's hash chain and may be billed. There is no endpoint to delete an ingested event. Use a separate test workspace (ask RegEngine for one) and keep the TEST- prefix on lot codes.

Post to /api/v1/webhooks/ingest. The sample builds a current timestamp, signs the exact body, and sends the same bytes with --data-binary:

bash

NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
TODAY=$(date -u +%Y-%m-%d)

BODY=$(cat <<EOF
{
  "source": "<your source system id>",
  "events": [
    {
      "cte_type": "receiving",
      "traceability_lot_code": "<the lot code you assigned>",
      "product_description": "<product name>",
      "quantity": "<number greater than 0>",
      "unit_of_measure": "<cases | lbs | kg | pallets | each>",
      "location_name": "<your facility name>",
      "timestamp": "$NOW",
      "kdes": {
        "receive_date": "$TODAY",
        "receiving_location": "<where the lot arrived>",
        "immediate_previous_source": "<who sent it to you>",
        "reference_document": "<your ASN or receipt id>",
        "tlc_source_reference": "<the lot reference your supplier gave you>"
      }
    }
  ]
}
EOF
)

# Sign the exact bytes you send: sha256= plus the HMAC-SHA256 hex digest.
SIGNATURE="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$REGENGINE_SIGNING_SECRET" -hex | sed 's/^.* //')"

curl -X POST https://regengine.co/api/v1/webhooks/ingest \
  -H "X-RegEngine-API-Key: $REGENGINE_API_KEY" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data-binary "$BODY"

A 200 carries one result per event:

json

{
  "accepted": 1,
  "rejected": 0,
  "total": 1,
  "events": [
    {
      "traceability_lot_code": "<the lot code you sent>",
      "cte_type": "receiving",
      "status": "accepted",
      "event_id": "<event UUID>",
      "sha256_hash": "<event hash>",
      "chain_hash": "<chain hash>",
      "errors": []
    }
  ],
  "ingestion_timestamp": "<server time, ISO 8601>",
  "ingestion_run_id": null
}

What the request needs

X-RegEngine-API-Key with the webhooks.ingest scope.
X-Webhook-Signature: sha256= followed by the HMAC-SHA256 hex digest of the exact request body bytes, keyed with the signing secret RegEngine issues. A missing or wrong signature returns 401.
Idempotency-Key: required (400 if missing, 255 characters at most). Use a new UUID for every new payload. Repeating a key with the same bytes within 24 hours replays the first successful response, including a 200 that rejected events. Repeating it with different bytes returns 409. After you fix a rejected event, send it with a new key.
Each event timestamp must fall within the last 90 days and no more than 24 hours ahead. An event older than 90 days comes back with status: "rejected" inside a 200. An event more than 24 hours ahead fails the whole request with a 422 and nothing is stored.
A RECEIVING event needs receive_date, receiving_location, immediate_previous_source, reference_document and tlc_source_reference (21 CFR §1.1345). Other event types need different KDEs; the API reference lists them.

A 200 does not mean every event was accepted. Check status on each event: a rejected one has errors explaining why, for example Missing required KDE 'reference_document' for receiving CTE. A 402 means the workspace has no active subscription; contact RegEngine. If you get a 429, stop for 60 seconds before retrying; see Rate Limits. Python and JavaScript versions of this call are on the docs home page.

Read the event back

Filter the records endpoint by lot code:

bash

curl -s "https://regengine.co/api/v1/records?tlc=<the lot code you sent>" \
  -H "X-RegEngine-API-Key: $REGENGINE_API_KEY"

json

{
  "tenant_id": "<your workspace ID>",
  "events": [
    {
      "event_id": "<event UUID>",
      "event_type": "receiving",
      "traceability_lot_code": "<the lot code you sent>",
      "product_reference": "<product name>",
      "quantity": "<number>",
      "unit_of_measure": "<unit>",
      "event_timestamp": "<the timestamp you sent>",
      "source_system": "webhook_api",
      "status": "active"
    }
  ],
  "total": 1
}

The list also carries from_facility_reference, to_facility_reference, confidence_score, schema_version and created_at; they are left out above. Each record's event_id opens the full record with provenance at GET /api/v1/records/{event_id}.

Next Steps

NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ) TODAY=$(date -u +%Y-%m-%d) BODY=$(cat <<EOF { "source": "<your source system id>", "events": [ { "cte_type": "receiving", "traceability_lot_code": "<the lot code you assigned>", "product_description": "<product name>", "quantity": "<number greater than 0>", "unit_of_measure": "<cases | lbs | kg | pallets | each>", "location_name": "<your facility name>", "timestamp": "$NOW", "kdes": { "receive_date": "$TODAY", "receiving_location": "<where the lot arrived>", "immediate_previous_source": "<who sent it to you>", "reference_document": "<your ASN or receipt id>", "tlc_source_reference": "<the lot reference your supplier gave you>" } } ] } EOF ) # Sign the exact bytes you send: sha256= plus the HMAC-SHA256 hex digest. SIGNATURE="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$REGENGINE_SIGNING_SECRET" -hex | sed 's/^.* //')" curl -X POST https://regengine.co/api/v1/webhooks/ingest \ -H "X-RegEngine-API-Key: $REGENGINE_API_KEY" \ -H "X-Webhook-Signature: $SIGNATURE" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ --data-binary "$BODY"

{ "accepted": 1, "rejected": 0, "total": 1, "events": [ { "traceability_lot_code": "<the lot code you sent>", "cte_type": "receiving", "status": "accepted", "event_id": "<event UUID>", "sha256_hash": "<event hash>", "chain_hash": "<chain hash>", "errors": [] } ], "ingestion_timestamp": "<server time, ISO 8601>", "ingestion_run_id": null }

{ "tenant_id": "<your workspace ID>", "events": [ { "event_id": "<event UUID>", "event_type": "receiving", "traceability_lot_code": "<the lot code you sent>", "product_reference": "<product name>", "quantity": "<number>", "unit_of_measure": "<unit>", "event_timestamp": "<the timestamp you sent>", "source_system": "webhook_api", "status": "active" } ], "total": 1 }