Skip to main content

Bot Execute

Invoke a Medplum Bot using the custom $execute operation.

If you're not familiar with Medplum Bots, you may want to review Bot Basics documentation first.

Invoke a bot by ID​

Invoke a bot by ID when you know the Bot's ID in advance.

You can find the id of your Bot by clicking on the Details tab of the Bot resource. In this example, it is 43ac3060-ff20-49e8-9682-bf91ab3a5191

Find your Bot ID
POST [base]/Bot/[id]/$execute

For example:

curl 'https://api.medplum.com/fhir/R4/Bot/MY_BOT_ID/$execute' \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer MY_ACCESS_TOKEN" \
  -d '{"foo":"bar"}'

The MedplumClient TypeScript class provides a executeBot convenience method:

  const result = await medplum.executeBot(id, { input: '...' });
  console.log(result);

Invoke a bot by identifier​

Sometimes you may not know the Medplum Bot ID in advance. In that case, you can invoke a Bot by Identifier.

This is also useful when the same conceptual bot exists in multiple Medplum projects. Each bot will have a different ID, but they can all have the same identifier.

POST [base]/Bot/$execute?identifier=[system]|[code]

For example:

curl 'https://api.medplum.com/fhir/R4/Bot/$execute?identifier=https://example.com/bots|1234' \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer MY_ACCESS_TOKEN" \
  -d '{"foo":"bar"}'

The MedplumClient executeBot convenience method supports both id: string and identifier: Identifier:

  const result = await medplum.executeBot(
    {
      system: 'https://example.com/bots',
      value: '1234',
    },
    {
      input1: '...',
      input2: '...',
    }
  );
  console.log(result);

Content Types​

Medplum Bots support a variety of input content types. Specify the input content type using the standard Content-Type HTTP header, or as an optional parameter to MedplumClient.executeBot().

Content-Typetypeof event.inputDescription
text/plainstring<INPUT_DATA> is parsed as plaintext string
application/jsonRecord<string, any><INPUT_DATA> is parsed as JSON-encoded object
application/x-www-form-urlencoded Record<string, string><INPUT_DATA> is parsed as URL-encoded string, resulting in a key/value map
application/fhir+jsonResource<INPUT_DATA> is parsed as a FHIR Resource encoded as JSON
x-application/hl7-v2+er7HL7Message<INPUT_DATA> is a string that should be parsed as a pipe-delimited HL7v2 message. HL7v2 is a common text-based message protocol used in legacy healthcare systems

The input data that will be parsed according to CONTENT_TYPE and passed into your Bot as event.input.