Tasks via API

Everything in the Tasks concept page is drivable over the Automation API: create tasks from templates, create them in bulk, and work them — discussion, files, status — programmatically.

Base URL: https://medchatapp.com/automationapi · Scopes: read.tasks for reads, write.tasks for writes, read.automations to read templates.

The task object

GET /orgs/{orgId}/tasks/{taskId} returns the full task: title, description, status (Draft, InProgress, Paused, Done, Cancelled), priority (None → Urgent), labels, assignedToUserId, needsAttention, todos, files, links, and analyzerOutputs.

Two link types are worth knowing:

• TaskRelationshipLink — parent/child relationships between tasks (relationshipType: Parent | Child).
• InteractionLink — the connection to a conversation (interactionType + interactionId). This is how a task points at the live chat or voice call it belongs to.

Create a task from a template

Templates govern the task's shape; you supply only the parameters the template declares. (Prefer a step-by-step walkthrough? See the Create a Task from a Template recipe.)

1. Find the template and read its parameters. Attributes with usage of TaskCreationParameter or Both are your inputs — keys match the attribute name:

curl "https://medchatapp.com/automationapi/orgs/$ORG_ID/taskTemplates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $TOKEN"

2. Instantiate it:

curl -X POST "https://medchatapp.com/automationapi/orgs/$ORG_ID/taskTemplates/$TEMPLATE_ID/createTask" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "patientName": "Jane Doe",
      "followUpDate": "2026-08-11"
    }
  }'

Response: 204 with Location: /automationapi/orgs/{orgId}/tasks/{taskId} — follow it to read the materialized task. Pass parentTaskId in the body to create the task as a sub-task.

Ad-hoc tasks (no template) are a plain POST /orgs/{orgId}/tasks with title, description, status, etc.

Create tasks in bulk

(Recipe: Bulk-Create Tasks from a Spreadsheet.)

A task batch applies one template to many parameter rows — you parse the source (CSV, spreadsheet, database) client-side and post structured rows:

curl -X POST "https://medchatapp.com/automationapi/orgs/$ORG_ID/taskBatches" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "taskTemplateId": "'$TEMPLATE_ID'",
    "sourceLabel": "outreach-august.csv",
    "rows": [
      { "parameters": { "patientName": "Jane Doe",  "followUpDate": "2026-08-11" } },
      { "parameters": { "patientName": "John Roe",  "followUpDate": "2026-08-12" } }
    ]
  }'

Parameter values are typed JSON (numbers as numbers, booleans as booleans), not strings. The batch runs asynchronously — poll the Location until status is Completed or Failed, and inspect rows[] for per-row results:

curl "https://medchatapp.com/automationapi/orgs/$ORG_ID/taskBatches/$BATCH_ID" \
  -H "Authorization: Bearer $TOKEN"

Bulk operations on existing tasks: POST /orgs/{orgId}/tasks/bulk/assign and POST /orgs/{orgId}/tasks/bulk/status.

Work a task

(Recipe: Work and Close a Task.)

Find work with OData:

curl "https://medchatapp.com/automationapi/orgs/$ORG_ID/tasks?\$filter=status eq 'InProgress' and needsAttention eq true" \
  -H "Authorization: Bearer $TOKEN"

Post to the discussion — the task's running record, shared by humans and AI agents:

curl -X POST "https://medchatapp.com/automationapi/orgs/$ORG_ID/tasks/$TASK_ID/discussion/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": [ { "type": "TextMessageBlock", "text": "Insurance verified; scheduling follow-up." } ]
  }'

replyToMessageId/threadId support threading; fileIds attaches uploaded files. GET .../discussion/mentioncandidates lists who can be mentioned; POST .../discussion/subscribe opts you into updates.

Attach a file with the three-step chunked upload:

1. POST .../tasks/{taskId}/files/initiate with { fileName, totalSize, mimeType } → returns fileId
2. POST .../files/{fileId}/chunks — repeat per chunk (multipart/form-data: chunkIndex, chunk)
3. POST .../files/{fileId}/finalize

Then GET .../files/{fileId}/download retrieves it.

Close it out with a JSON Patch:

curl -X PATCH "https://medchatapp.com/automationapi/orgs/$ORG_ID/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[ { "op": "replace", "path": "/status", "value": "Done" } ]'

Notes

• Analyzer results for a task: GET /orgs/{orgId}/tasks/{taskId}/analyzerOutputs.
• Grants appear on task reads but are read-only via the API today — author them in the app UI.
• Tasks participate in the shared edit/version model — every change bumps the task's edit, and version history is queryable.