ReferenceFlows API

Approvals & forms

Approvals and forms waiting for you, and answering them.

Method	Path	Summary
GET	`/api/actions/:token`	Open an action link
POST	`/api/actions/:token`	Answer an action link
GET	`/api/waits`	Approvals and forms waiting for me
GET	`/api/waits/:id`	Get an approval or form
POST	`/api/waits/:id/answer`	Answer an approval or form

#Open an action link

GET/api/actions/:token

Address: https://<your-org>.brambleit.cloud/flows/api/actions/:token
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Flows.

Path parameters

Name	Type	Description
`token`required	string

Response 200

Field	Type	Description
`action`	object
`action.label`	string
`action.title`	string
`action.expired`	boolean
`action.flow`	any
`action.clicks`	array of any
`action.last_clicked_at`	string (date-time)
`action.last_clicked_by`	any

Example response

JSON

{
  "action": {
    "label": "Example label",
    "title": "Example title",
    "expired": false,
    "flow": null,
    "clicks": [],
    "last_clicked_at": "2026-11-12T09:30:00.000Z",
    "last_clicked_by": null
  }
}

Errors

Status	Message
404	This link isn't valid

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/flows/api/actions/%E2%80%A6', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Answer an action link

POST/api/actions/:token

Address: https://<your-org>.brambleit.cloud/flows/api/actions/:token
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Flows.

Path parameters

Name	Type	Description
`token`required	string

Response 200

Errors

Status	Message
404	This link isn't valid

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/flows/api/actions/%E2%80%A6', {
  method: 'POST',
  credentials: 'include',
});
const data = await res.json();

#Approvals and forms waiting for me

GET/api/waits

Address: https://<your-org>.brambleit.cloud/flows/api/waits
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Flows.

Response 200

Field	Type	Description
`waits`	array of any

Example response

JSON

{
  "waits": []
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/flows/api/waits', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Get an approval or form

GET/api/waits/:id

Address: https://<your-org>.brambleit.cloud/flows/api/waits/:id
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Flows.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`wait`	object
`wait.id`	integer
`wait.kind`	string
`wait.title`	string
`wait.details`	any
`wait.spec`	any
`wait.needs`	array of any
`wait.status`	string
`wait.expired`	boolean
`wait.result`	any
`wait.created_at`	string (date-time)
`wait.expires_at`	string (date-time)
`wait.decided_at`	string (date-time)
`wait.run_id`	integer
`wait.flow`	object, or null
`wait.flow.id`	integer
`wait.flow.name`	string
`wait.people`	array of object
`wait.people[].email`	string
`wait.people[].name`	string
`wait.people[].decision`	any
`wait.people[].note`	string
`wait.people[].decided_at`	string (date-time)
`me`	object, or null
`me.decision`	any
`me.can_answer`	boolean

Example response

JSON

{
  "wait": {
    "id": 42,
    "kind": "string",
    "title": "Example title",
    "details": null,
    "spec": null,
    "needs": [],
    "status": "active",
    "expired": false,
    "result": null,
    "created_at": "2026-11-12T09:30:00.000Z",
    "expires_at": "2026-11-12T09:30:00.000Z",
    "decided_at": "2026-11-12T09:30:00.000Z",
    "run_id": 7,
    "flow": {
      "id": 42,
      "name": "Example name"
    },
    "people": [
      {
        "email": "alex@example.com",
        "name": "Example name",
        "decision": null,
        "note": "string",
        "decided_at": "2026-11-12T09:30:00.000Z"
      }
    ]
  },
  "me": {
    "decision": null,
    "can_answer": true
  }
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/flows/api/waits/42', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Answer an approval or form

POST/api/waits/:id/answer

Address: https://<your-org>.brambleit.cloud/flows/api/waits/:id/answer
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Flows.

Path parameters

Name	Type	Description
`id`required	integer

Request body JSON

Name	Type	Description
`answers`	array of any	The form's answers (forms).
`approve`	boolean	`true` to approve, `false` to reject (approvals).
`note`	string	A note.

Response 200

Errors

Status	Message
403	You weren't asked

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/flows/api/waits/42/answer', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"answers":[],"approve":false,"note":"string"}),
});
const data = await res.json();

Was this page helpful?