Views API

Saved lists — the columns, filters and order you chose.

Module code view_grid · 5 actions · 2 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: view_grid (everything), view_grid:read (read only) or view_grid:<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

view_grid.copy_base_views

Copy Base views — Copies shared views and your personal views onto copied Base tables.

Needs view_grid:write · changes data

• Canonical address: POST /api/v1/actions/view_grid.copy_base_views

Input

Preconditions

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

Events it publishes: view_grid.saved

What it writes: saved_view (insert) — Copies visible views onto the copied tables

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

{
  "ok": true,
  "result": "…",
  "events": [
    "view_grid.saved"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.savedViews.copyBaseViews({
  tableMap: {},
  columnMap: {}
})

era saved_views copy_base_views --data '{"tableMap":{},"columnMap":{}}'

{
  "name": "era__view_grid__copy_base_views",
  "arguments": {
    "tableMap": {},
    "columnMap": {}
  }
}

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

view_grid.delete

Delete a view — Removes a saved view.

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

• Canonical address: POST /api/v1/actions/view_grid.delete

Input

Preconditions

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

Events it publishes: view_grid.deleted

What it writes: saved_view (delete) — Deletes the view

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

{
  "ok": true,
  "result": "…",
  "events": [
    "view_grid.deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.savedViews.delete({
  view_id: "VIEW_ID"
})

era saved_views delete \
  --view-id "VIEW_ID"

{
  "name": "era__view_grid__delete",
  "arguments": {
    "view_id": "VIEW_ID"
  }
}

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

view_grid.remember

Remember where I left this list — Stores one person’s unsaved arrangement of one list.

Needs view_grid:read · changes data

• Canonical address: POST /api/v1/actions/view_grid.remember

Input

Preconditions

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

What it writes: view_state (update) — Stores the arrangement

curl -X POST https://app.getera.io/api/v1/view_states/actions/remember \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"module_code":"Module","view_key":"List","state":"Arrangement"}'

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.viewStates.remember({
  module_code: "Module",
  view_key: "List",
  state: "Arrangement"
})

era view_states remember \
  --module-code "Module" \
  --view-key "List" \
  --state "Arrangement"

{
  "name": "era__view_grid__remember",
  "arguments": {
    "module_code": "Module",
    "view_key": "List",
    "state": "Arrangement"
  }
}

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

view_grid.save

Save this view — Names the current arrangement of a list so it can be returned to.

Needs view_grid:write · changes data

• Canonical address: POST /api/v1/actions/view_grid.save

Input

Preconditions

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

Events it publishes: view_grid.saved, view_grid.shared

What it writes: saved_view (insert) — Saves the view

curl -X POST https://app.getera.io/api/v1/saved_views/actions/save \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"module_code":"Module","view_key":"List","name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "view_grid.saved",
    "view_grid.shared"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.savedViews.save({
  module_code: "Module",
  view_key: "List",
  name: "Name"
})

era saved_views save \
  --module-code "Module" \
  --view-key "List" \
  --name "Name"

{
  "name": "era__view_grid__save",
  "arguments": {
    "module_code": "Module",
    "view_key": "List",
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold view_grid:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unknown_module, invalid_shape, name_taken, cannot_share · 429 slow down

view_grid.update

Change a saved view — Renames a view, or stores the arrangement it is currently showing.

Needs view_grid:write · changes data

• Canonical address: POST /api/v1/actions/view_grid.update

Input

Preconditions

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

Events it publishes: view_grid.saved

What it writes: saved_view (update) — Rewrites the view

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

{
  "ok": true,
  "result": "…",
  "events": [
    "view_grid.saved"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.savedViews.update({
  view_id: "VIEW_ID"
})

era saved_views update \
  --view-id "VIEW_ID"

{
  "name": "era__view_grid__update",
  "arguments": {
    "view_id": "VIEW_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold view_grid:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, not_yours, invalid_shape, name_taken, no_change, view_locked · 429 slow down

Data models

SavedView

Table saved_view · Resource saved_views

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

Primary key: id

Checks:

• CHECK ((jsonb_typeof(columns) = 'array'::text))
• CHECK ((jsonb_typeof(conditions) = 'object'::text))
• CHECK ((jsonb_typeof(options) = 'object'::text))
• CHECK ((jsonb_typeof(sorts) = 'array'::text))

ViewState

Table view_state · Resource view_states

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

Primary key: workspace_id, user_id, module_code, view_key

Checks:

• CHECK ((jsonb_typeof(state) = 'object'::text))

Events

Workflows and webhooks react to these events.