AlmondTill/G3N API

Give the team its work — tasks, labels, hand-offs

Create tasks for people or teams, move them through their life, label them to organize the board, park one until a chosen moment — it comes back by itself — and leave a permanent note on any record.

Work · a play in 4 steps.

The steps

  1. Create the task — assigned to people or teams. — createTask
  2. Move it on — take it, complete it, cancel it — or park it until a chosen moment. — transitionTask, postponeTask
  3. Create the labels that organize the board. — createTaskLabel
  4. Attach a permanent note — with files when needed — to any record, and react to a note with a mark everyone can see. — addNote, mintNoteAttachmentUpload, reactToNote

The calls

Every operation this use case runs, in the order it first appears, with the request and the response its reference page shows.

createTask

createTask — mutation · Create a new task — a to-do assigned to people or teams at your organization.

Example request

mutation ExampleCreateTask($input: NewTaskInput!) {
  createTask(input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    description
    priority
    createdBy
    systemOrigin
    reportTo
    assigneeUserIds
    teamIds
    labelIds
    dueAt
    overdue
    linkedFromTaskId
    returnAt
    originNoteId
    originAnchorType
    originAnchorId
  }
}

Variables:

{
  "input": {
    "caption": "Blue jeans"
  }
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "createTask": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TK-EXMP-0000-000F",
      "type": "Task",
      "caption": "Blue jeans",
      "status": "open",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "description": "Straight-cut, mid-rise, five pockets.",
      "priority": "<priority>",
      "createdBy": "01900000-0000-7000-8000-0b14e5a60000",
      "systemOrigin": "<system origin>",
      "reportTo": "01900000-0000-7000-8000-9d69c9660000",
      "assigneeUserIds": [
        "01900000-0000-7000-8000-fbe5fcb10000"
      ],
      "teamIds": [
        "01900000-0000-7000-8000-1abd3d160000"
      ],
      "labelIds": [
        "01900000-0000-7000-8000-a235e7410000"
      ],
      "dueAt": "2027-01-31T00:00:00.000Z",
      "overdue": true,
      "linkedFromTaskId": "01900000-0000-7000-8000-6de8c4e00000",
      "returnAt": "2027-01-31T00:00:00.000Z",
      "originNoteId": "01900000-0000-7000-8000-f1eb5d520000",
      "originAnchorType": "<origin anchor type>",
      "originAnchorId": "01900000-0000-7000-8000-323b002b0000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

transitionTask

transitionTask — mutation · Move a task through its life — take it, complete it, cancel it, or pull a postponed one back now.

Example request

mutation ExampleTransitionTask($id: ID!, $revision: ID!, $op: TaskTransitionOp!, $reason: String) {
  transitionTask(id: $id, revision: $revision, op: $op, reason: $reason) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    description
    priority
    createdBy
    systemOrigin
    reportTo
    assigneeUserIds
    teamIds
    labelIds
    dueAt
    overdue
    linkedFromTaskId
    returnAt
    originNoteId
    originAnchorType
    originAnchorId
  }
}

Variables:

{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "op": "start",
  "reason": "Correcting a miscount."
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "transitionTask": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TK-EXMP-0000-000F",
      "type": "Task",
      "caption": "Blue jeans",
      "status": "open",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "description": "Straight-cut, mid-rise, five pockets.",
      "priority": "<priority>",
      "createdBy": "01900000-0000-7000-8000-0b14e5a60000",
      "systemOrigin": "<system origin>",
      "reportTo": "01900000-0000-7000-8000-9d69c9660000",
      "assigneeUserIds": [
        "01900000-0000-7000-8000-fbe5fcb10000"
      ],
      "teamIds": [
        "01900000-0000-7000-8000-1abd3d160000"
      ],
      "labelIds": [
        "01900000-0000-7000-8000-a235e7410000"
      ],
      "dueAt": "2027-01-31T00:00:00.000Z",
      "overdue": true,
      "linkedFromTaskId": "01900000-0000-7000-8000-6de8c4e00000",
      "returnAt": "2027-01-31T00:00:00.000Z",
      "originNoteId": "01900000-0000-7000-8000-f1eb5d520000",
      "originAnchorType": "<origin anchor type>",
      "originAnchorId": "01900000-0000-7000-8000-323b002b0000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

postponeTask

postponeTask — mutation · Park a task until a chosen moment — it leaves the inboxes and comes back BY ITSELF at that time (the boomerang).

Example request

mutation ExamplePostponeTask($id: ID!, $revision: ID!, $returnAt: String!, $reason: String) {
  postponeTask(id: $id, revision: $revision, returnAt: $returnAt, reason: $reason) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    description
    priority
    createdBy
    systemOrigin
    reportTo
    assigneeUserIds
    teamIds
    labelIds
    dueAt
    overdue
    linkedFromTaskId
    returnAt
    originNoteId
    originAnchorType
    originAnchorId
  }
}

Variables:

{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "returnAt": "2027-01-31T00:00:00.000Z",
  "reason": "Correcting a miscount."
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "postponeTask": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "TK-EXMP-0000-000F",
      "type": "Task",
      "caption": "Blue jeans",
      "status": "open",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "description": "Straight-cut, mid-rise, five pockets.",
      "priority": "<priority>",
      "createdBy": "01900000-0000-7000-8000-0b14e5a60000",
      "systemOrigin": "<system origin>",
      "reportTo": "01900000-0000-7000-8000-9d69c9660000",
      "assigneeUserIds": [
        "01900000-0000-7000-8000-fbe5fcb10000"
      ],
      "teamIds": [
        "01900000-0000-7000-8000-1abd3d160000"
      ],
      "labelIds": [
        "01900000-0000-7000-8000-a235e7410000"
      ],
      "dueAt": "2027-01-31T00:00:00.000Z",
      "overdue": true,
      "linkedFromTaskId": "01900000-0000-7000-8000-6de8c4e00000",
      "returnAt": "2027-01-31T00:00:00.000Z",
      "originNoteId": "01900000-0000-7000-8000-f1eb5d520000",
      "originAnchorType": "<origin anchor type>",
      "originAnchorId": "01900000-0000-7000-8000-323b002b0000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

createTaskLabel

createTaskLabel — mutation · Create a new label for organizing tasks at your organization.

Example request

mutation ExampleCreateTaskLabel($input: NewTaskLabelInput!) {
  createTaskLabel(input: $input) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    color
  }
}

Variables:

{
  "input": {
    "caption": "Blue jeans"
  }
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "createTaskLabel": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "LB-EXMP-0000-000F",
      "type": "TaskLabel",
      "caption": "Blue jeans",
      "status": "active",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "color": "<color>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

addNote

addNote — mutation · Attach a note (optionally with files) to any record — an order, a product, a customer.

Example request

mutation ExampleAddNote($input: NewNoteInput!) {
  addNote(input: $input) {
    id
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    targetType
    authorId
    parentNoteId
    title
    kind
    body
    labelIds
    taskId
  }
}

Variables:

{
  "input": {
    "targetConstructId": "01900000-0000-7000-8000-79e077380000",
    "targetType": "<target type>",
    "body": "Restock before the weekend.",
    "parentNoteId": "01900000-0000-7000-8000-907baa100000"
  }
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "addNote": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "type": "<type>",
      "caption": "Blue jeans",
      "status": "<status>",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "targetType": "<target type>",
      "authorId": "01900000-0000-7000-8000-0046e40b0000",
      "parentNoteId": "01900000-0000-7000-8000-907baa100000",
      "title": "Blue jeans",
      "kind": "<kind>",
      "body": "Restock before the weekend.",
      "labelIds": [
        "01900000-0000-7000-8000-a235e7410000"
      ],
      "taskId": "01900000-0000-7000-8000-6ceba5410000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

mintNoteAttachmentUpload

mintNoteAttachmentUpload — mutation · Get a short-lived, pre-authorized upload slot for a note attachment.

Example request

mutation ExampleMintNoteAttachmentUpload($input: MintNoteAttachmentUploadInput!) {
  mintNoteAttachmentUpload(input: $input) {
    attachmentId
    key
    uploadUrl
    expiresAt
  }
}

Variables:

{
  "input": {
    "targetConstructId": "01900000-0000-7000-8000-79e077380000",
    "targetType": "<target type>",
    "filename": "<filename>",
    "declaredContentType": "<declared content type>",
    "bytes": 1,
    "sha256": "<sha256>"
  }
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "mintNoteAttachmentUpload": {
      "attachmentId": "01900000-0000-7000-8000-7bdf12b50000",
      "key": "<key>",
      "uploadUrl": "https://example.com/hook",
      "expiresAt": "2027-01-31T00:00:00.000Z"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

reactToNote

reactToNote — mutation · React to a note with one of the canned emojis — a lightweight mark everyone can see and count.

Example request

mutation ExampleReactToNote($targetConstructId: ID!, $noteId: ID!, $emoji: String!) {
  reactToNote(targetConstructId: $targetConstructId, noteId: $noteId, emoji: $emoji) {
    emoji
    count
    userIds
  }
}

Variables:

{
  "targetConstructId": "01900000-0000-7000-8000-79e077380000",
  "noteId": "01900000-0000-7000-8000-cf06f4680000",
  "emoji": "<emoji>"
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "reactToNote": [
      {
        "emoji": "<emoji>",
        "count": 1,
        "userIds": [
          "01900000-0000-7000-8000-f79e33c40000"
        ]
      }
    ]
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}