Shared views & forms API

Share a Base view with a private link, or publish it as a form.

Module code data_sharing · 3 actions · 1 data models · 3 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_sharing (everything), data_sharing:read (read only) or data_sharing:<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_sharing.create_link

Share a view — Publishes a view on a secret link — read-only, or a form strangers can fill in.

Needs data_sharing:manage · changes data

• Canonical address: POST /api/v1/actions/data_sharing.create_link

Input

Preconditions

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

Events it publishes: data_sharing.link_created

What it writes: data_share (insert) — Creates the link

curl -X POST https://app.getera.io/api/v1/data_shares/actions/create_link \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"savedViewId":"SAVED_VIEW_ID","scope":"read"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "data_sharing.link_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dataShares.createLink({
  savedViewId: "SAVED_VIEW_ID",
  scope: "read"
})

era data_shares create_link \
  --saved-view-id "SAVED_VIEW_ID" \
  --scope "read"

{
  "name": "era__data_sharing__create_link",
  "arguments": {
    "savedViewId": "SAVED_VIEW_ID",
    "scope": "read"
  }
}

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

data_sharing.revoke_link

Revoke a shared link — The link stops working at once, for everyone who has it.

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

• Canonical address: POST /api/v1/actions/data_sharing.revoke_link

Input

Preconditions

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

Events it publishes: data_sharing.link_revoked

What it writes: data_share (update) — Switches the link off

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

{
  "ok": true,
  "result": "…",
  "events": [
    "data_sharing.link_revoked"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dataShares.revokeLink("DATA_SHARE_ID")

era data_shares revoke_link DATA_SHARE_ID

{
  "name": "era__data_sharing__revoke_link",
  "arguments": {
    "id": "DATA_SHARE_ID"
  }
}

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

data_sharing.update_link

Change a shared link — Sets or removes its password and expiry, and whether it allows a download.

Needs data_sharing:manage · changes data

• Canonical address: POST /api/v1/actions/data_sharing.update_link

Input

Preconditions

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

Events it publishes: data_sharing.link_changed

What it writes: data_share (update) — Changes the link

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

{
  "ok": true,
  "result": "…",
  "events": [
    "data_sharing.link_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.dataShares.updateLink("DATA_SHARE_ID", {
  password: "New password"
})

era data_shares update_link DATA_SHARE_ID \
  --password "New password"

{
  "name": "era__data_sharing__update_link",
  "arguments": {
    "id": "DATA_SHARE_ID",
    "password": "New password"
  }
}

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

Data models

DataShare

Table data_share · Resource data_shares

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

Primary key: id

Unique: token

Events

Workflows and webhooks react to these events.