API Conventions

The platform APIs share one set of conventions. Learn them once and every service reads the same way.

Media types

Responses use the versioned media type application/vnd.medchat+json;v=1.0. Request bodies are accepted as either that type or plain application/json.

Accept: application/vnd.medchat+json;v=1.0
Content-Type: application/json

Writes return 204 + Location

Creates and updates return 204 No Content with a Location header pointing at the resource — never 201 with a body. To read what you created, follow the Location (or re-GET the resource).

HTTP/1.1 204 No Content
Location: /automationapi/orgs/{orgId}/tasks/{taskId}
x-aggregate-edit: 1

On the Automation API, writes also return x-aggregate-edit — the resource's new edit number (see Edits and versions below).

Querying lists with OData

List endpoints support OData query options: $filter, $orderby, $select, $expand, $count, $skip, and $top (capped at 100).

curl "https://medchatapp.com/automationapi/orgs/$ORG_ID/tasks?\$filter=status eq 'InProgress'&\$orderby=dueDateTime&\$top=50" \
  -H "Authorization: Bearer $TOKEN"

The Total-Count response header carries the total matching count when requested.

Partial updates use JSON Patch

PATCH endpoints take a JSON Patch array. This is also how nested collections (a playbook's procedures, a task's todos) are edited:

[
  { "op": "replace", "path": "/status", "value": "Done" }
]

Edits and versions (Automation API)

Every mutation of an automation resource (playbook, task, template, AI agent, …) increments its integer edit. Edits group into versions:

• GET .../{id}/versions — the version history; GET .../{id}/versions/{versionId}/edits shows the individual changes inside one.
• POST .../{id}/finalizeVersion with { "lastEdit": <n> } seals the active version — a 409 means the resource changed under you; re-read and retry.
• Point-in-time reads: GET .../{id}?edit=<n> or ?asOf=<timestamp> (mutually exclusive).
• POST .../{id}/revert restores a previous edit; POST .../{id}/duplicate clones under a new name.

References between resources can pin an edit or float: an AI agent's assigned playbook is { "playbookId": "...", "playbookEdit": "latest" } or a specific integer.

Export and import

Automation resources round-trip as YAML — the standard way to move configuration between environments:

• GET .../{id}/export (optionally ?edit= / ?asOf=) downloads the YAML.
• POST .../import (multipart/form-data, up to 30 MB) creates the resource in the target org.

Soft delete

DELETE soft-deletes; POST .../{id}/restore undoes it.

Error reference