Getting Started with the APIs

Everything you can do in Elegant Machine's UI is backed by HTTP APIs, and most of it is available to your own integrations. This page covers the two things every API consumer needs first: where the APIs live, and how to authenticate.

Base URLs

Elegant Machine's APIs are served on the medchatapp.com domain, one path prefix per service:

API	Base URL
Automation API (tasks, playbooks, AI agents, templates)	`https://medchatapp.com/automationapi`
Live Chat API	`https://medchatapp.com/livechatapi2.0`
Voice Chat API	`https://medchatapp.com/voicechatapi`

Each service publishes an interactive Swagger explorer at {baseUrl}/swagger and its OpenAPI document at {baseUrl}/swagger/v1/swagger.json.

Authentication overview

To call the APIs you need your Org ID and a scoped API access token. Both live in the developer area of the app: Admin › Developer › Auth (visible to users with the Developer role).

Tokens are passed as a bearer credential on every request:

curl "https://medchatapp.com/automationapi/orgs/$ORG_ID/tasks?\$top=5" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.medchat+json;v=1.0"

Almost every endpoint is org-scoped — the {orgId} in the URL must be the org your token was issued for. Calling another org's URL returns 403 even with a valid token.

Managing access tokens

Tokens are created, rotated, and revoked on the Auth screen at Admin › Developer › Auth — see the Auth page for the full walkthrough. Two rules worth knowing up front: a token is displayed once, at creation; and its scopes and expiration can't be changed afterward — changing access means rotating to a new token.

Scopes

Scopes map to permissions the APIs check on every request. The ones relevant to the currently documented surface:

Domain	Scope	What it unlocks
Tasks	`read.tasks`	Read tasks, batches, discussion, files, analyzer outputs
	`write.tasks`	Create/update tasks, instantiate templates, batches, discussion posts, file uploads
Automation resources	`read.automations`	Read playbooks, AI agents, task templates, data types, knowledge sets, custom AI actions, analyzer configurations
	`manage.automations`	Create/update/delete those same resources
Live chats	`read.my_orgs.chats`	Read all of your org's chats, transcripts, and files
Voice	`read.voice_chats`	Read call logs, transcripts, and AI evaluations
	`read.voice_chat_phone_numbers`	Read phone numbers and their voice configuration
Custom Reports	`read.analytics_query_results`	Execute report queries and read/export results
Datasets	`manage.dataset`	Create, update, and delete datasets
	`get.dataset`	Read and query datasets

A caller only needs one of the permissions listed on an endpoint — where docs list several, they are alternatives, not requirements.

📘
Grants are read-only via the API today. Reading a resource returns its grants, but modifying a grants collection requires an elevated permission that isn't currently available on scoped access tokens. Author grants in the app UI.

Errors you'll meet first

Status	Meaning
`401`	Missing, expired, or invalid token
`403`	Valid token, but missing the required scope — or the URL's `{orgId}` doesn't match your org
`400`	Validation failure; the body is a dictionary of field names to error messages

Next: API Conventions — the request/response patterns shared by every service.

Base URLs

Authentication overview

Managing access tokens

Scopes

Grants are read-only via the API today. Reading a resource returns its grants, but modifying a grants collection requires an elevated permission that isn't currently available on scoped access tokens. Author grants in the app UI.

Errors you'll meet first

Grants are read-only via the API today. Reading a resource returns its `grants`, but modifying a `grants` collection requires an elevated permission that isn't currently available on scoped access tokens. Author grants in the app UI.