Tags API

One shared set of tags for every record, in your own colours.

Module code tags · 6 actions · 2 data models · 6 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: tags (everything), tags:read (read only) or tags:<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

tags.attach

Tag a record — Puts an existing tag on a record. Needs permission to edit that record.

Needs tags:read · changes data

• Canonical address: POST /api/v1/actions/tags.attach

Input

Preconditions

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

Events it publishes: tags.attached

What it writes: tag_link (insert) — Attaches the tag

curl -X POST https://app.getera.io/api/v1/tag_links/actions/attach \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tagId":"TAG_ID","recordType":"Record type","recordId":"RECORD_ID"}'

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.tagLinks.attach({
  tagId: "TAG_ID",
  recordType: "Record type",
  recordId: "RECORD_ID"
})

era tag_links attach \
  --tag-id "TAG_ID" \
  --record-type "Record type" \
  --record-id "RECORD_ID"

{
  "name": "era__tags__attach",
  "arguments": {
    "tagId": "TAG_ID",
    "recordType": "Record type",
    "recordId": "RECORD_ID"
  }
}

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

tags.create

Create a tag — Adds an entry to the workspace vocabulary every module shares.

Needs tags:manage · changes data

• REST alias: POST /api/v1/tags
• Canonical address: POST /api/v1/actions/tags.create

Input

Preconditions

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

Events it publishes: tags.created

What it writes: tag (insert) — Writes the vocabulary entry

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

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.tags.create({
  name: "Name"
})

era tags create \
  --name "Name"

{
  "name": "era__tags__create",
  "arguments": {
    "name": "Name"
  }
}

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

tags.delete

Delete a tag — Removes the entry and every attachment it has. Says how many before it does.

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

• REST alias: DELETE /api/v1/tags/{id}
• Canonical address: POST /api/v1/actions/tags.delete

Input

Preconditions

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

Events it publishes: tags.deleted

What it writes: tag (delete) — Removes the entry; tag_link (delete) — Its attachments go with it, by cascade

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

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.tags.delete("TAG_ID")

era tags delete TAG_ID

{
  "name": "era__tags__delete",
  "arguments": {
    "id": "TAG_ID"
  }
}

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

tags.detach

Remove a tag from a record — Takes a tag off a record without touching the vocabulary.

Needs tags:read · changes data

• Canonical address: POST /api/v1/actions/tags.detach

Input

Preconditions

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

Events it publishes: tags.detached

What it writes: tag_link (delete) — Detaches the tag

curl -X POST https://app.getera.io/api/v1/tag_links/actions/detach \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tagId":"TAG_ID","recordType":"Record type","recordId":"RECORD_ID"}'

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.tagLinks.detach({
  tagId: "TAG_ID",
  recordType: "Record type",
  recordId: "RECORD_ID"
})

era tag_links detach \
  --tag-id "TAG_ID" \
  --record-type "Record type" \
  --record-id "RECORD_ID"

{
  "name": "era__tags__detach",
  "arguments": {
    "tagId": "TAG_ID",
    "recordType": "Record type",
    "recordId": "RECORD_ID"
  }
}

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

tags.merge

Merge two tags — Moves everything from one entry onto another and removes the empty one.

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

• Canonical address: POST /api/v1/actions/tags.merge

Input

Preconditions

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

Events it publishes: tags.merged

What it writes: tag_link (update) — Repoints the attachments; tag (delete) — Removes the entry that was merged away

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

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.tags.merge("TAG_ID", {
  loserId: "TAG_ID"
})

era tags merge TAG_ID \
  --loser-id "TAG_ID"

{
  "name": "era__tags__merge",
  "arguments": {
    "winnerId": "TAG_ID",
    "loserId": "TAG_ID"
  }
}

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

tags.update

Rename or recolour a tag — Changes the entry itself. Nothing already tagged is touched.

Needs tags:manage · changes data

• REST alias: PATCH /api/v1/tags/{id}
• Canonical address: POST /api/v1/actions/tags.update

Input

Preconditions

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

Events it publishes: tags.updated

What it writes: tag (update) — Rewrites the entry

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

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

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.tags.update("TAG_ID", {
  name: "Name"
})

era tags update TAG_ID \
  --name "Name"

{
  "name": "era__tags__update",
  "arguments": {
    "id": "TAG_ID",
    "name": "Name"
  }
}

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

Data models

TagLink

Table tag_link · Resource tag_links

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

Primary key: id

Tag

Table tag · Resource tags

• GET /api/v1/tags
• GET /api/v1/tags/{id}
• POST /api/v1/tags → tags.create
• PATCH /api/v1/tags/{id} → tags.update
• DELETE /api/v1/tags/{id} → tags.delete

Primary key: id

Checks:

• CHECK (((color IS NULL) OR (color ~ '^#[0-9A-Fa-f]{6}$'::text)))
• CHECK (((name = btrim(name)) AND (length(name) > 0)))
• CHECK (((slug = lower(slug)) AND (slug = btrim(slug)) AND (length(slug) > 0)))

Events

Workflows and webhooks react to these events.