Ingest table events - Autotouch AI

This page documents the canonical HTTP contract for this endpoint.

This authenticated endpoint checks the caller's table access, then appends each supplied record as one row. It returns accepted and rowIds. Developer keys require tables:write; the authenticated user must also have table access. It does not use a webhook token; use the separate table webhook endpoint for unauthenticated source delivery.

Use an event-source table when modeling an append-only stream. Each record is retained whole under webhook_payload, with its top-level properties also written to row fields. The example event fields are not schema requirements.

Path parameters

table_idrequired
string
Target Research Table ID.

Name	Type	Description
table_idrequired	string	Target Research Table ID.

Body parameters

records · optional
array<EventRecord>
Optional array of open JSON event objects; each becomes a row. May be combined with record.
record · optional
EventRecord
Optional open JSON event object; appended after records when both are supplied.
additional event fields · optional
JSON object properties
Open JSON properties may be sent at the top level as a single event when neither records nor record is supplied. Top-level extra properties are ignored when records or record is present.

Name	Type	Description
records	array<EventRecord>	Optional array of open JSON event objects; each becomes a row. May be combined with record.
record	EventRecord	Optional open JSON event object; appended after records when both are supplied.
additional event fields	JSON object properties	Open JSON properties may be sent at the top level as a single event when neither records nor record is supplied. Top-level extra properties are ignored when records or record is present.

Definitions

EventRecord

An open JSON object with no required event-specific keys. Its fields are written as row fields and the full object is also stored under webhook_payload. The example fields below are illustrative only.

Fields

event_type · optional
string
Illustrative event name; choose the value used by your integration.
occurred_at · optional
string (date-time)
Event time in ISO 8601 form.
external_id · optional
string
Optional source-system event or entity identifier.
properties · optional
object
Optional event-specific values; nested JSON is preserved.

Name	Type	Description
event_type	string	Illustrative event name; choose the value used by your integration.
occurred_at	string (date-time)	Event time in ISO 8601 form.
external_id	string	Optional source-system event or entity identifier.
properties	object	Optional event-specific values; nested JSON is preserved.

EventRecord example

json

{
  "event_type": "demo_requested",
  "occurred_at": "2026-09-27T14:00:00Z",
  "external_id": "evt_example_01",
  "properties": { "source": "website", "plan": "team" }
}

Errors

Status	Meaning
401	Missing or invalid authentication.
403	Table access denied or the key is missing tables:write.
404	Table not found.
422	No event record was supplied or the request is invalid.

Example

bash

curl -X POST "https://app.autotouch.ai/api/tables/TABLE_ID/events" \
  -H "Authorization: Bearer stk_your_key_id.your_secret" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"event_type":"demo_requested","occurred_at":"2026-09-27T14:00:00Z","external_id":"evt_example_01","properties":{"source":"website"}}]}'

Request body

json

{
  "records": [
    {
      "event_type": "demo_requested",
      "occurred_at": "2026-09-27T14:00:00Z",
      "external_id": "evt_example_01",
      "properties": { "source": "website", "plan": "team" }
    },
    {
      "event_type": "trial_started",
      "occurred_at": "2026-09-27T14:05:00Z",
      "external_id": "evt_example_02",
      "properties": { "source": "website", "plan": "team" }
    }
  ]
}

Response example

json

{
  "accepted": 2,
  "rowIds": ["000000000000000000000001", "000000000000000000000002"]
}