Actions and task tools

Send an action to a client's Asana, ClickUp or monday as one task, pick where its tasks go, and read what was sent and what is done.

GET /clients/{brandId}/handoff-targets

Read a client's task tools, where its tasks go, and every action sent to one.

Note

With tool, targets lists the places that tool's account can take a task, for picking one: that listing is a member's or above, under the write limit, at most 200 calls to the tool (partial and note say when the list was cut short), and kept ten minutes per client and tool. Without tool any seat reads the rest. A client's own login reads empty lists.

About this route	Detail
Returns	configured, tools (asana, clickup and monday, each with status, null when not connected, and target, the project, list or board picked), sent (by action key: tool, taskId, url, sentAt, sentBy and doneAt) and targets.
Seat	A key on a member seat or above. A viewer's key is refused with 403.
Plan	Every plan.
Rate limit	30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget	Nothing this route does is metered.

Parameter	Type	What it is
brandId (path, required)	uuid	A brand id from GET /brands.
tool (query)	one of asana, clickup, monday	List where this tool's account can take a task.

curl "https://api.ansengine.co/clients/{brandId}/handoff-targets" \
  -H "Authorization: Bearer ak_your_key"

Status	When
200	configured, tools (asana, clickup and monday, each with status, null when not connected, and target, the project, list or board picked), sent (by action key: tool, taskId, url, sentAt, sentBy and doneAt) and targets.
400	brandId is not a valid id, or tool is not asana, clickup or monday.
401	No valid API key was sent.
404	No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.
429	Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait.

PUT /clients/{brandId}/handoff-target

Pick where a client's tasks go in one task tool.

About this route	Detail
Returns	ok, tool and target. Every later send of this client to that tool lands there.
Seat	A key on a member seat or above. A viewer's key is refused with 403.
Plan	Every plan.
Rate limit	30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget	Nothing this route does is metered.

Parameter	Type	What it is
brandId (path, required)	uuid	A brand id from GET /brands.

The body is JSON. Its schema, taken from the route's own validation:

{
  "type": "object",
  "properties": {
    "tool": {
      "type": "string",
      "enum": [
        "asana",
        "clickup",
        "monday"
      ]
    },
    "target": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 300
        }
      },
      "required": [
        "id",
        "name"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "tool",
    "target"
  ],
  "additionalProperties": false
}

curl -X PUT "https://api.ansengine.co/clients/{brandId}/handoff-target" \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  --data @body.json

Status	When
200	ok, tool and target. Every later send of this client to that tool lands there.
400	brandId is not a valid id, or the body does not match the schema.
401	No valid API key was sent.
403	The key belongs to a viewer seat, which can read and cannot write.
404	No such brand for this key. A brand in another workspace and a client outside this seat's view answer the same way, so a 404 never confirms that an id exists.
409	That tool is not connected for this client: connect it on the Connections page first.
429	Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait.

POST /actions/{actionId}/handoff

Send one action to a client's Asana, ClickUp or monday as one task.

Note

actionId is the action's key, URL encoded, as the Actions view lists it. The task carries the brief, a link back to the action and the client's name.

About this route	Detail
Returns	ok, already and handoff (tool, taskId, url, sentAt, sentBy, doneAt). An action is sent once: a second send answers already: true with the first task, whatever the tool.
Seat	A key on a member seat or above. A viewer's key is refused with 403.
Plan	Every plan.
Rate limit	30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own.
Engine budget	Nothing this route does is metered.

Parameter	Type	What it is
actionId (path, required)	uuid	The action id.

The body is JSON. Its schema, taken from the route's own validation:

{
  "type": "object",
  "properties": {
    "brandId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "tool": {
      "type": "string",
      "enum": [
        "asana",
        "clickup",
        "monday"
      ]
    }
  },
  "required": [
    "brandId",
    "tool"
  ],
  "additionalProperties": false
}

curl -X POST "https://api.ansengine.co/actions/{actionId}/handoff" \
  -H "Authorization: Bearer ak_your_key" \
  -H "Content-Type: application/json" \
  --data @body.json

Status	When
200	ok, already and handoff (tool, taskId, url, sentAt, sentBy, doneAt). An action is sent once: a second send answers already: true with the first task, whatever the tool.
400	actionId is not an action's key, or the body does not match the schema.
401	No valid API key was sent.
403	The key belongs to a viewer seat, which can read and cannot write.
404	No such brand for this key, or no such action in its Actions view.
409	The tool is not connected for this client, or no project, list or board is picked yet.
429	Over the rate limit: 30 requests a minute for the workspace, counted across every write that takes this limit, the console's included. A seat limited to named clients gets 15 of its own. The Retry-After header says how many seconds to wait.
502	The tool did not create the task. Nothing was recorded; send again.
503	Connections are not configured on this deployment.