Automation API - Perform

/v1/automation is the lane automation platforms talk to. It was built for Make first, and the same surface works for any HTTP client. The MCP server and the WhatsApp AI assistant also execute their tools through it. Source: apps/core-api/src/modules/automation-api. Webhook subscriptions under /hooks are in apps/core-api/src/modules/automation-hooks and are documented in Outbound webhooks. Base URL in production: https://perform-api.otherwise.co.il/v1/automation.

Authentication

A studio API key as a bearer token:

GET /v1/automation/validate
Authorization: Bearer YOUR_API_KEY

The lane uses the same requirePartnerKey middleware as the partner lane. Every request resolves to exactly one studio, and all reads and writes are scoped to it. See Partner API and API keys for how keys are created and verified.

Envelope

This lane does not use the standard ok and data envelope, and it does not share the global error middleware. Automation clients show a failed step’s message straight to a coach, so every error has to read as a sentence that says what to fix. Success, always HTTP 200:

{ "success": true, "message": "Connection is working", "data": { "studioId": "STUDIO_ID", "studioName": "STUDIO_NAME", "slug": "studio-slug" } }

Failure:

{ "success": false, "message": "A trainee with phone 0500000000 already exists in this studio (TRAINEE_NAME). Set \"On duplicate phone\" to \"return existing\" or \"update\" if that is expected." }

Error mapping

automationErrorMiddleware in automation-api.envelope.ts is registered on this router only.

Thrown	HTTP status	Message
`ZodError`	400	”Invalid request: ” followed by up to 5 issues as readable phrases, for example “phone is required”
`AppError` `UNAUTHORIZED`	401	The error’s message
`AppError` `FORBIDDEN`	403	The error’s message. Plan limit refusals arrive here.
`AppError` `CONFLICT`	409	The error’s message
`AppError` `RATE_LIMITED`	429	The error’s message
`AppError` `SERVICE_UNAVAILABLE`	503	The error’s message
`AppError` `INTERNAL`	500	The error’s message
Any other `AppError` (`NOT_FOUND`, `BAD_REQUEST`, `VALIDATION`)	400	The error’s message. These all mean “the caller can fix this”.
Anything else	500	The error’s message

backend/docs/MAKE_MODULE_AGENT_PROMPT.md says every response is HTTP 200. That is not what the code does. Failures carry real status codes. A client should treat a response as failed when success is false, whatever the status.

Input coercion

Automation platforms serialize everything as strings and send empty strings for “not filled in”. The schemas in automation-api.schema.ts coerce far more than the web lane so a coach does not need formula steps to satisfy the validator.

Helper	Behaviour
`blankToUndefined`	`null` and a blank string both become `undefined`. No field on this lane uses `null` to mean “clear it”.
`makeString`, `makeOptionalString`	Non-empty string after the blank rule.
`makeBool`	Accepts `true` and `false` as strings. An empty string reads as `false`, `null` as not provided.
`makeNumber`, `makeInt`, `makeDate`	Coerced after the blank rule.
`optionalNumber`, `optionalInt`	Optional numbers with the optionality inside the preprocess. Written the other way round, a blank became `NaN` and failed validation.
`makeTags`	An array, or a comma-separated string. Up to 50 tags.
`fieldValues`	Coach-side values for a document to sign. Accepts an array of `{ key, value }`, a JSON string, or a plain object. All become one map of strings.

Pagination on list endpoints: limit (default 50, max 200) and offset (default 0).

Endpoints

Connection

Route	Returns
`GET /validate`	`{ studioId, studioName, slug }`. Make calls it when a coach adds the connection.

Trainees

Route	Purpose
`GET /trainees/search`	Search and filter.
`GET /trainees/by-phone/:phone`	Find by phone. Message is “Trainee found” or “No trainee with that phone”.
`POST /trainees`	Create.
`GET /trainees/:id`	Read one.
`PATCH /trainees/:id`	Update.
`DELETE /trainees/:id`	Delete, with confirmation.

GET /trainees/search query: q, status (a ClientStatus), coachId, tag, createdAfter, updatedAfter, limit, offset.

`POST /trainees`

string

required

string

required

string

required

Normalized to Perform’s canonical form before anything else.

string

Your own id for this trainee. The strongest key the API has.

date

string

MALE, FEMALE or OTHER.

number

string

integer

string[] or comma-separated string

string[]

Up to 20.

string

A plan to assign at creation.

date

integer

Required when the plan does not fix its own price.

integer

Required when the plan does not fix its own duration. The error names the plan and the field.

string

DAYS or MONTHS.

string

WEEKLY, BIWEEKLY or MONTHLY.

boolean

default:"false"

Send the WhatsApp invite. Off by default, so a bulk import never texts hundreds of people by surprise.

string

default:"error"

error, return_existing or update.

There is no notify field. Creating a trainee reaches them in exactly one way, the WhatsApp invite, which has its own flag. How duplicates are resolved, in createTrainee:

externalId is checked first. If a trainee with that external id exists, it is returned with created: false. This is what makes a retried scenario safe.
Then the phone, matched through phone variants. What happens next depends on onDuplicatePhone: error fails with CONFLICT and a message naming the existing trainee, return_existing returns it, update applies the body to it.
Otherwise a new trainee is created inside withTraineeRoom, so the plan’s trainee limit applies.

The response is { trainee, created }. External ids are stored namespaced in Client.externalUserId as automation:<studioId>:<externalId>. Responses and webhook payloads hand back only the part the caller supplied.

`DELETE /trainees/:id`

Body: confirm, default false. Without confirm: true nothing is deleted and the response is a success envelope explaining that deleting a trainee erases their whole history and cannot be undone. That is deliberate. A scenario wired without reading the warning gets an explanation, not a validation error that hides why nothing happened.

Subscriptions

Route	Body	Returns
`GET /trainees/:id/subscriptions`		The trainee’s subscriptions.
`POST /trainees/:id/subscription`	`productId` (required), `startedOn`, `priceAgorot`, `durationValue`, `durationUnit`, `notify` (default `true`)	`data.subscription`: every live subscription of the trainee (scheduled, active and frozen), ordered by start date. Not only the one just created.
`POST /trainees/:id/subscription/freeze`		`data.subscriptions`
`POST /trainees/:id/subscription/reactivate`		`data.subscriptions`
`POST /trainees/:id/subscription/cancel`	`subscriptionId` (required)	`data.subscriptions`

Note the singular key on assign and the plural on the three lifecycle calls. That is the API. When startedOn is omitted, the new plan starts when the trainee’s last live plan ends, not today. Today would land inside the running plan and be refused by the overlap guard, which is what every renewal of an active trainee was hitting.

Programs

Route	Body	Purpose
`GET /trainees/:id/programs`		The trainee’s programs. Returns `{ items }`.
`POST /trainees/:id/programs/assign`	`templateId` (required), `startsOn`, `notify` (default `true`), `replaceExisting` (default `false`)	Assign a program from a template.
`GET /program-templates`		Templates. Query `search`, `limit`, `offset`.

Forms

Route	Purpose
`GET /forms`	Forms. Query `search`, `limit`, `offset`.
`GET /trainees/:id/form-responses`	The trainee’s submitted forms.
`POST /trainees/:id/forms/assign`	Send a form.

POST /trainees/:id/forms/assign body:

Field	Notes
`formTemplateId`	Required. An inactive form is refused.
`dueAt`	Optional date.
`notify`	Three states. See below.
`prompt`	Optional message, up to 500 characters.
`fieldValues`	Documents to sign only: values of the coach-filled fields, by field key. Ignored for other form types.

notify deliberately has no default:

Value	Effect
`true`	Push the trainee right away.
left blank (omitted, `null` or an empty string)	The hourly pending-form notifier announces the form once, under the studio’s settings, and only once the trainee can open it. Like a coach-assigned form, minus the instant push.
`false`, sent explicitly	The form stays silent for good. This lane exists for bulk syncs, and a caller who asks for silence gets it.

For a document to sign (PDF_SIGNATURE) nothing is sent to the trainee app. The response carries signingUrl, the trainee’s personal signing link, and the message is “Signing link created”. The caller delivers that link itself.

Weights

Route	Body
`GET /trainees/:id/weights`
`POST /trainees/:id/weights`	`weightKg` (positive, up to 500), `recordedAt`

Messages

POST /trainees/:id/message with message (1 to 1000 characters) sends a push notification to the trainee app. It returns { sent, selected, unreachable, disabled }. sent counts devices that actually accepted. sent: 0 is not an error. It means no reachable device.

Tasks

Route	Body or query
`GET /tasks`	Query `status` (`OPEN`, `SNOOZED`, `DONE`, `DISMISSED`), `clientId`, `coachId`, `limit`, `offset`
`POST /tasks`	`title` (required), `clientId`, `detail` (up to 2000), `dueAt`, `priority` (0 to 5, default 1), `coachId`
`PATCH /tasks/:id`	`status`, `snoozeUntil`, `priority` (0 to 5)

Plans

GET /products lists the studio’s plans. Query search, limit, offset. priceAgorot and durationValue can be null, which means the plan fixes no value and it is set per trainee. 0 means free. They are different facts. These return short id and label lists for a client’s dropdowns:

Route	Lists
`GET /rpc/products`	Plans. A plan with no fixed price is labelled as priced per trainee, server-side.
`GET /rpc/coaches`	Coaches.
`GET /rpc/forms`	Published, active forms.
`GET /rpc/program-templates`	Program templates.
`GET /rpc/tags`	Trainee tags.
`GET /rpc/form-fields`	The coach-filled fields of a document to sign. Query `formTemplateId`.

Webhooks

POST /hooks, GET /hooks, DELETE /hooks/:id. See Outbound webhooks.

Pagination shapes

Five endpoints return { items, total, limit, offset, hasMore }: /trainees/search, /tasks, /products, /program-templates and /forms. Four return only { items } and cannot page: /trainees/:id/programs, /trainees/:id/form-responses, /trainees/:id/weights and /trainees/:id/subscriptions.

Notifications from this lane

Bulk automation must not spray push notifications at real trainees. The notifier is injected at construction and not per call, so the router keeps two service instances, one loud and one silent, and picks per request from the notify flag. “Silent” only means no instant push from this process. A form assigned silently is still picked up by the hourly pending-form notifier, unless the request said notify: false outright.

Audit

Writes are recorded in AuditLog with the API key id as the actor. Actions written by this lane: automation.trainee.create, automation.trainee.delete, automation.subscription.assign, automation.program.assign, automation.task.create, and from the hooks module automation.hook.register and automation.hook.remove.

Plan limits

Creating a trainee goes through the studio’s plan guard. A studio at its trainee limit gets HTTP 403 with a message saying so.

Existing documentation

backend/docs/AUTOMATION_API.md is a prose guide to this lane and backend/docs/AUTOMATION_API_PLAN.md is the original plan. Where they disagree with the Zod schemas and the routes, the code is right.

​Authentication

​Envelope

​Error mapping

​Input coercion

​Endpoints

​Connection

​Trainees

​POST /trainees

​DELETE /trainees/:id

​Subscriptions

​Programs

​Forms

​Weights

​Messages

​Tasks

​Plans

​Dropdown sources

​Webhooks

​Pagination shapes

​Notifications from this lane

​Audit

​Plan limits

​Existing documentation

Authentication

Envelope

Error mapping

Input coercion

Endpoints

Connection

Trainees

`POST /trainees`

`DELETE /trainees/:id`

Subscriptions

Programs

Forms

Weights

Messages

Tasks

Plans

Dropdown sources

Webhooks

Pagination shapes

Notifications from this lane

Audit

Plan limits

Existing documentation