Table sync API

Keep a table filled from an outside database, Airtable, a Google Sheet or a CSV link — or in step with your customers, both ways.

Module code data_sync · 7 actions · 2 data models · 8 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: data_sync (everything), data_sync:read (read only) or data_sync:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

data_sync.create_sync

Sync a table from a source — Points a table at a source outside the platform and says how its fields map.

Needs data_sync:manage · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/data_sync.create_sync

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: data_sync.sync_created

What it writes: data_sync (insert) — Writes the sync

curl -X POST https://app.getera.io/api/v1/data_syncs/actions/create_sync \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"dataTableId":"DATA_TABLE_ID","title":"Name","sourceKind":"postgres","sourceConfig":{},"fieldMap":{},"sourceKey":"Source key field"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "data_sync.sync_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dataSyncs.createSync({
  dataTableId: "DATA_TABLE_ID",
  title: "Name",
  sourceKind: "postgres",
  sourceConfig: {},
  fieldMap: {},
  sourceKey: "Source key field"
})

era data_syncs create_sync --data '{"dataTableId":"DATA_TABLE_ID","title":"Name","sourceKind":"postgres","sourceConfig":{},"fieldMap":{},"sourceKey":"Source key field"}'

{
  "name": "era__data_sync__create_sync",
  "arguments": {
    "dataTableId": "DATA_TABLE_ID",
    "title": "Name",
    "sourceKind": "postgres",
    "sourceConfig": {},
    "fieldMap": {},
    "sourceKey": "Source key field"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold data_sync:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 sync_table_not_found, invalid_source_config, credential_required, key_field_unknown, invalid_field_map · 429 slow down

data_sync.delete_sync

Remove a sync — Stops syncing. The records it wrote stay in the table.

Needs data_sync:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/data_sync.delete_sync

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: data_sync.sync_deleted

What it writes: data_sync (delete) — Removes the sync and its run history

curl -X POST https://app.getera.io/api/v1/data_syncs/DATA_SYNC_ID/actions/delete_sync \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "data_sync.sync_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dataSyncs.deleteSync("DATA_SYNC_ID")

era data_syncs delete_sync DATA_SYNC_ID

{
  "name": "era__data_sync__delete_sync",
  "arguments": {
    "id": "DATA_SYNC_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold data_sync:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 sync_not_found, sync_running · 429 slow down

data_sync.record_run

Record a sync run’s progress — The sync job’s bookkeeping: counts, the checkpoint and the outcome.

Needs data_sync:handle · changes data

• Canonical address: POST /api/v1/actions/data_sync.record_run

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: data_sync.run_succeeded, data_sync.run_failed

What it writes: data_sync_run (update) — Adds the counts and the outcome; data_sync (update) — Moves the checkpoint and the health

curl -X POST https://app.getera.io/api/v1/data_sync_runs/DATA_SYNC_RUN_ID/actions/record_run \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"status":"running"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "data_sync.run_succeeded",
    "data_sync.run_failed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dataSyncRuns.recordRun("DATA_SYNC_RUN_ID", {
  status: "running"
})

era data_sync_runs record_run DATA_SYNC_RUN_ID \
  --status "running"

{
  "name": "era__data_sync__record_run",
  "arguments": {
    "runId": "DATA_SYNC_RUN_ID",
    "status": "running"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold data_sync:handle · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 run_not_found, run_already_finished · 429 slow down

data_sync.request_run

Sync now — Queues a run as a platform job. A full run re-reads everything and can notice deletions.

Needs data_sync:manage · changes data

• Canonical address: POST /api/v1/actions/data_sync.request_run

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: data_sync.run_requested

What it writes: data_sync_run (insert) — Queues the run; data_sync (update) — Marks the sync queued

curl -X POST https://app.getera.io/api/v1/data_syncs/DATA_SYNC_ID/actions/request_run \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"fullRefresh":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "data_sync.run_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dataSyncs.requestRun("DATA_SYNC_ID", {
  fullRefresh: true
})

era data_syncs request_run DATA_SYNC_ID \
  --full-refresh true

{
  "name": "era__data_sync__request_run",
  "arguments": {
    "id": "DATA_SYNC_ID",
    "fullRefresh": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold data_sync:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 sync_not_found, sync_paused, sync_running, credential_required · 429 slow down

data_sync.retry_run

Retry a failed run — Queues a new run from the last committed checkpoint.

Needs data_sync:manage · changes data

• Canonical address: POST /api/v1/actions/data_sync.retry_run

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: data_sync.run_requested

What it writes: data_sync_run (insert) — Queues the retry; data_sync (update) — Marks the sync queued

curl -X POST https://app.getera.io/api/v1/data_sync_runs/DATA_SYNC_RUN_ID/actions/retry_run \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "data_sync.run_requested"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dataSyncRuns.retryRun("DATA_SYNC_RUN_ID")

era data_sync_runs retry_run DATA_SYNC_RUN_ID

{
  "name": "era__data_sync__retry_run",
  "arguments": {
    "runId": "DATA_SYNC_RUN_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold data_sync:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 run_not_found, run_not_failed, sync_not_found, sync_paused, sync_running, credential_required · 429 slow down

data_sync.set_paused

Pause or resume a sync — A paused sync keeps its checkpoint and its schedule does not fire.

Needs data_sync:manage · changes data

• Canonical address: POST /api/v1/actions/data_sync.set_paused

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: data_sync.sync_paused, data_sync.sync_resumed

What it writes: data_sync (update) — Flips it between paused and idle

curl -X POST https://app.getera.io/api/v1/data_syncs/DATA_SYNC_ID/actions/set_paused \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"paused":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "data_sync.sync_paused",
    "data_sync.sync_resumed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dataSyncs.setPaused("DATA_SYNC_ID", {
  paused: true
})

era data_syncs set_paused DATA_SYNC_ID \
  --paused true

{
  "name": "era__data_sync__set_paused",
  "arguments": {
    "id": "DATA_SYNC_ID",
    "paused": true
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold data_sync:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 sync_not_found · 429 slow down

data_sync.update_sync

Change a sync — Changes what it reads or how it maps. A changed key or source starts the next run from the beginning.

Needs data_sync:manage · changes data

• Canonical address: POST /api/v1/actions/data_sync.update_sync

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: data_sync.sync_changed

What it writes: data_sync (update) — Rewrites the sync

curl -X POST https://app.getera.io/api/v1/data_syncs/DATA_SYNC_ID/actions/update_sync \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "data_sync.sync_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dataSyncs.updateSync("DATA_SYNC_ID", {
  title: "Name"
})

era data_syncs update_sync DATA_SYNC_ID \
  --title "Name"

{
  "name": "era__data_sync__update_sync",
  "arguments": {
    "id": "DATA_SYNC_ID",
    "title": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold data_sync:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 sync_not_found, invalid_source_config, credential_required, key_field_unknown, invalid_field_map · 429 slow down

Data models

DataSyncRun

Table data_sync_run · Resource data_sync_runs

• GET /api/v1/data_sync_runs
• GET /api/v1/data_sync_runs/{id}

Primary key: id

Checks:

• CHECK ((jsonb_typeof(errors) = 'array'::text))

DataSync

Table data_sync · Resource data_syncs

• GET /api/v1/data_syncs
• GET /api/v1/data_syncs/{id}

Primary key: id

Checks:

• CHECK (((jsonb_typeof(source_config) = 'object'::text) AND (jsonb_typeof(field_map) = 'object'::text)))
• CHECK (((schedule_minutes IS NULL) OR ((schedule_minutes >= 5) AND (schedule_minutes <= 10080))))
• CHECK ((btrim(title) <> ''::text))
• CHECK (((NOT two_way) OR (source_kind = 'module'::text)))

Events

Workflows and webhooks react to these events.