# Care flows
URL: https://docs.awellhealth.com/api-reference/reference/care-flows

> For the complete documentation index, see [llms.txt](https://docs.awellhealth.com/llms.txt).



Start, stop, pause, and inspect care flows, their activities, and their data points.

## Queries [#queries]

### `baselineInfo` [#baselineinfo]

Returns the baseline info data points for a care flow.

**Arguments**

| Argument     | Type      | Required | Description             |
| ------------ | --------- | -------- | ----------------------- |
| `pathway_id` | `String!` | Yes      | The ID of the care flow |

**Returns:** `BaselineInfoPayload!`

**Example**

```graphql
query BaselineInfo($pathway_id: String!) {
  baselineInfo(pathway_id: $pathway_id) {
    baselineDataPoints {
      definition {
        category
        id
        key
        optional
        pii
        source_definition_id
        title
        unit
        valueType
      }
      value
    }
    code
    success
  }
}
```

Variables:

```json
{
  "pathway_id": "<string>"
}
```

### `baselineInfoLog` [#baselineinfolog]

Returns a paginated log of a care flow's baseline info data points.

**Arguments**

| Argument                   | Type               | Required | Description                                                                                                  |
| -------------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `data_point_definition_id` | `String`           | No       | The ID of the data point definition                                                                          |
| `data_point_key`           | `String`           | No       | The key of the data point                                                                                    |
| `pagination`               | `PaginationParams` | No       | How many results to return and the offset to start from — see [Pagination](/api-reference/guides/pagination) |
| `pathway_id`               | `String!`          | Yes      | The ID of the care flow                                                                                      |
| `sorting`                  | `SortingParams`    | No       | The field to sort by and the sort direction — see [Pagination](/api-reference/guides/pagination)             |

**Returns:** `BaselineInfoLogPayload!`

**Example**

```graphql
query BaselineInfoLog($data_point_definition_id: String, $data_point_key: String, $pagination: PaginationParams, $pathway_id: String!, $sorting: SortingParams) {
  baselineInfoLog(data_point_definition_id: $data_point_definition_id, data_point_key: $data_point_key, pagination: $pagination, pathway_id: $pathway_id, sorting: $sorting) {
    code
    dataPoints {
      activity_id
      data_point_definition_id
      data_set_id
      date
      id
      key
      label
      serialized_value
      status
      valueType
    }
    pagination {
      count
      offset
      total_count
    }
    sorting {
      direction
      field
    }
    success
  }
}
```

Variables:

```json
{
  "data_point_definition_id": "<string>",
  "data_point_key": "<string>",
  "pagination": {
    "count": 0,
    "offset": 0
  },
  "pathway_id": "<string>",
  "sorting": {
    "direction": "<string>",
    "field": "<string>"
  }
}
```

### `getPublishedCareflowVersions` [#getpublishedcareflowversions]

Lists the published versions (releases) of a care flow definition.

**Arguments**

| Argument                 | Type     | Required | Description                        |
| ------------------------ | -------- | -------- | ---------------------------------- |
| `careflow_definition_id` | `String` | No       | The ID of the care flow definition |

**Returns:** `CareflowVersionsPayload!`

**Example**

```graphql
query GetPublishedCareflowVersions($careflow_definition_id: String) {
  getPublishedCareflowVersions(careflow_definition_id: $careflow_definition_id) {
    careflowVersions {
      careflow_definition_id
      versions {
        live
        release_date
        release_id
        title
        version
      }
    }
  }
}
```

Variables:

```json
{
  "careflow_definition_id": "<string>"
}
```

### `latestCareFlowDataPoints` [#latestcareflowdatapoints]

Returns the latest data point values for a care flow.

**Arguments**

| Argument      | Type      | Required | Description                                                    |
| ------------- | --------- | -------- | -------------------------------------------------------------- |
| `careflow_id` | `String!` | Yes      | The ID of the care flow                                        |
| `release_id`  | `String!` | Yes      | The ID of the published care flow definition version (release) |

**Returns:** `DataPointPayload!`

**Example**

```graphql
query LatestCareFlowDataPoints($careflow_id: String!, $release_id: String!) {
  latestCareFlowDataPoints(careflow_id: $careflow_id, release_id: $release_id) {
    code
    dataPoints {
      activity_id
      data_point_definition_id
      data_set_id
      date
      id
      key
      label
      serialized_value
      status
      valueType
    }
    pagination {
      count
      offset
      total_count
    }
    sorting {
      direction
      field
    }
    success
  }
}
```

Variables:

```json
{
  "careflow_id": "<string>",
  "release_id": "<string>"
}
```

### `pathway` [#pathway]

Retrieves a single care flow by its ID.

**Arguments**

| Argument | Type      | Required | Description             |
| -------- | --------- | -------- | ----------------------- |
| `id`     | `String!` | Yes      | The ID of the care flow |

**Returns:** `PathwayPayload!`

**Example**

```graphql
query Pathway($id: String!) {
  pathway(id: $id) {
    code
    pathway {
      complete_date
      created {
        date
        user_email
        user_id
        user_name
      }
      id
      is_archived
      latestActivities {
        action
        container_name
        date
        expires_at
        form_display_mode
        icon_url
        id
        isUserActivity
        metadata
        public
        reference_id
        reference_type
        resolution
        session_id
        status
        stream_id
      }
      pathway_definition_id
      patient {
        id
        tenant_id
      }
      patient_id
      release_id
      start_date
      status
      status_explanation
      stop_date
      title
      version
    }
    success
  }
}
```

Variables:

```json
{
  "id": "<string>"
}
```

### `pathwayActivities` [#pathwayactivities]

Activities of a care flow. Alias of careflowActivities — the original public name, kept for backward compatibility.

**Arguments**

| Argument     | Type               | Required | Description                                                                                                  |
| ------------ | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `pagination` | `PaginationParams` | No       | How many results to return and the offset to start from — see [Pagination](/api-reference/guides/pagination) |
| `pathway_id` | `String!`          | Yes      | The ID of the care flow                                                                                      |
| `sorting`    | `SortingParams`    | No       | The field to sort by and the sort direction — see [Pagination](/api-reference/guides/pagination)             |
| `track_id`   | `String`           | No       | The ID of the track                                                                                          |

**Returns:** `ActivitiesPayload!`

**Example**

```graphql
query PathwayActivities($pagination: PaginationParams, $pathway_id: String!, $sorting: SortingParams, $track_id: String) {
  pathwayActivities(pagination: $pagination, pathway_id: $pathway_id, sorting: $sorting, track_id: $track_id) {
    activities {
      action
      action_component {
        definition_id
        release_id
        title
      }
      container_name
      context {
        action_id
        agent_config_id
        agent_id
        agent_thread_id
        instance_id
        pathway_id
        run_id
        step_id
        track_id
      }
      date
      expires_at
      form {
        definition_id
        id
        key
        metadata
        release_id
        title
        trademark
      }
      form_display_mode
      icon_url
      id
      isUserActivity
      metadata
      public
      reference_id
      reference_type
      resolution
      session_id
      status
      stream_id
    }
    code
    metadata {
      stakeholders {
        email
        id
        name
        preferred_language
        type
      }
    }
    pagination {
      count
      offset
      total_count
    }
    success
  }
}
```

Variables:

```json
{
  "pagination": {
    "count": 0,
    "offset": 0
  },
  "pathway_id": "<string>",
  "sorting": {
    "direction": "<string>",
    "field": "<string>"
  },
  "track_id": "<string>"
}
```

### `pathwayDataPointDefinitions` [#pathwaydatapointdefinitions]

Lists the data point definitions for a care flow definition release.

**Arguments**

| Argument                | Type                                      | Required | Description                                                    |
| ----------------------- | ----------------------------------------- | -------- | -------------------------------------------------------------- |
| `filters`               | `FilterPathwayDataPointDefinitionsParams` | No       | Filters to narrow the results                                  |
| `pathway_definition_id` | `String`                                  | No       | The ID of the care flow definition                             |
| `release_id`            | `String!`                                 | Yes      | The ID of the published care flow definition version (release) |

**Returns:** `PathwayDataPointDefinitionsPayload!`

**Example**

```graphql
query PathwayDataPointDefinitions($filters: FilterPathwayDataPointDefinitionsParams, $pathway_definition_id: String, $release_id: String!) {
  pathwayDataPointDefinitions(filters: $filters, pathway_definition_id: $pathway_definition_id, release_id: $release_id) {
    code
    data_point_definitions {
      category
      id
      key
      metadata {
        key
        value
      }
      optional
      pii
      possibleValues {
        label
        value
      }
      range {
        max
        min
      }
      source_definition_id
      title
      unit
      valueType
    }
    success
  }
}
```

Variables:

```json
{
  "filters": {},
  "pathway_definition_id": "<string>",
  "release_id": "<string>"
}
```

### `pathwayDataPoints` [#pathwaydatapoints]

Returns the data points collected in a care flow.

**Arguments**

| Argument                   | Type               | Required | Description                                                                                                  |
| -------------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `activity_id`              | `String`           | No       | The ID of the activity                                                                                       |
| `data_point_definition_id` | `String`           | No       | The ID of the data point definition                                                                          |
| `data_point_key`           | `String`           | No       | The key of the data point                                                                                    |
| `pagination`               | `PaginationParams` | No       | How many results to return and the offset to start from — see [Pagination](/api-reference/guides/pagination) |
| `pathway_id`               | `String!`          | Yes      | The ID of the care flow                                                                                      |
| `sorting`                  | `SortingParams`    | No       | The field to sort by and the sort direction — see [Pagination](/api-reference/guides/pagination)             |

**Returns:** `DataPointPayload!`

**Example**

```graphql
query PathwayDataPoints($activity_id: String, $data_point_definition_id: String, $data_point_key: String, $pagination: PaginationParams, $pathway_id: String!, $sorting: SortingParams) {
  pathwayDataPoints(activity_id: $activity_id, data_point_definition_id: $data_point_definition_id, data_point_key: $data_point_key, pagination: $pagination, pathway_id: $pathway_id, sorting: $sorting) {
    code
    dataPoints {
      activity_id
      data_point_definition_id
      data_set_id
      date
      id
      key
      label
      serialized_value
      status
      valueType
    }
    pagination {
      count
      offset
      total_count
    }
    sorting {
      direction
      field
    }
    success
  }
}
```

Variables:

```json
{
  "activity_id": "<string>",
  "data_point_definition_id": "<string>",
  "data_point_key": "<string>",
  "pagination": {
    "count": 0,
    "offset": 0
  },
  "pathway_id": "<string>",
  "sorting": {
    "direction": "<string>",
    "field": "<string>"
  }
}
```

### `pathwayFacts` [#pathwayfacts]

Returns a paginated list of facts recorded for a care flow.

**Arguments**

| Argument     | Type                   | Required | Description                                                                                                  |
| ------------ | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `filters`    | `PathwayFactsFilters!` | Yes      | Filters to narrow the results                                                                                |
| `pagination` | `PaginationParams`     | No       | How many results to return and the offset to start from — see [Pagination](/api-reference/guides/pagination) |
| `sorting`    | `SortingParams`        | No       | The field to sort by and the sort direction — see [Pagination](/api-reference/guides/pagination)             |

**Returns:** `OrchestrationFactsPayload!`

**Example**

```graphql
query PathwayFacts($filters: PathwayFactsFilters!, $pagination: PaginationParams, $sorting: SortingParams) {
  pathwayFacts(filters: $filters, pagination: $pagination, sorting: $sorting) {
    code
    facts {
      content
      date
      level
      pathway_id
    }
    pagination {
      count
      offset
      total_count
    }
    sorting {
      direction
      field
    }
    success
  }
}
```

Variables:

```json
{
  "filters": {
    "pathway_id": "<string>"
  },
  "pagination": {
    "count": 0,
    "offset": 0
  },
  "sorting": {
    "direction": "<string>",
    "field": "<string>"
  }
}
```

### `pathways` [#pathways]

Lists care flows, with optional filtering, pagination, and sorting.

**Arguments**

| Argument     | Type               | Required | Description                                                                                                  |
| ------------ | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `filters`    | `FilterPathways`   | No       | Filters to narrow the results                                                                                |
| `pagination` | `PaginationParams` | No       | How many results to return and the offset to start from — see [Pagination](/api-reference/guides/pagination) |
| `sorting`    | `SortingParams`    | No       | The field to sort by and the sort direction — see [Pagination](/api-reference/guides/pagination)             |

**Returns:** `PathwaysPayload!`

**Example**

```graphql
query Pathways($filters: FilterPathways, $pagination: PaginationParams, $sorting: SortingParams) {
  pathways(filters: $filters, pagination: $pagination, sorting: $sorting) {
    code
    pagination {
      count
      offset
      total_count
    }
    pathways {
      complete_date
      id
      pathway_definition_id
      patient_id
      start_date
      status
      status_explanation
      stop_date
      title
      version
    }
    sorting {
      direction
      field
    }
    success
  }
}
```

Variables:

```json
{
  "filters": {},
  "pagination": {
    "count": 0,
    "offset": 0
  },
  "sorting": {
    "direction": "<string>",
    "field": "<string>"
  }
}
```

### `pathwayStepActivities` [#pathwaystepactivities]

Lists the activities for a step within a care flow.

**Arguments**

| Argument     | Type      | Required | Description             |
| ------------ | --------- | -------- | ----------------------- |
| `pathway_id` | `String!` | Yes      | The ID of the care flow |
| `step_id`    | `String!` | Yes      | The ID of the step      |

**Returns:** `ActivitiesPayload!`

**Example**

```graphql
query PathwayStepActivities($pathway_id: String!, $step_id: String!) {
  pathwayStepActivities(pathway_id: $pathway_id, step_id: $step_id) {
    activities {
      action
      action_component {
        definition_id
        release_id
        title
      }
      container_name
      context {
        action_id
        agent_config_id
        agent_id
        agent_thread_id
        instance_id
        pathway_id
        run_id
        step_id
        track_id
      }
      date
      expires_at
      form {
        definition_id
        id
        key
        metadata
        release_id
        title
        trademark
      }
      form_display_mode
      icon_url
      id
      isUserActivity
      metadata
      public
      reference_id
      reference_type
      resolution
      session_id
      status
      stream_id
    }
    code
    metadata {
      stakeholders {
        email
        id
        name
        preferred_language
        type
      }
    }
    pagination {
      count
      offset
      total_count
    }
    success
  }
}
```

Variables:

```json
{
  "pathway_id": "<string>",
  "step_id": "<string>"
}
```

### `publishedPathwayDefinitions` [#publishedpathwaydefinitions]

Lists the published care flow definitions.

**Returns:** `PublishedPathwayDefinitionsPayload!`

**Example**

```graphql
query PublishedPathwayDefinitions {
  publishedPathwayDefinitions {
    code
    pagination {
      count
      offset
      total_count
    }
    publishedPathwayDefinitions {
      created {
        date
        user_email
        user_id
        user_name
      }
      data_point_definitions {
        category
        id
        key
        optional
        pii
        source_definition_id
        title
        unit
        valueType
      }
      data_store_version
      id
      last_updated {
        date
        user_email
        user_id
        user_name
      }
      release_date
      release_id
      title
      version
    }
    sorting {
      direction
      field
    }
    success
  }
}
```

## Mutations [#mutations]

### `completeCareflow` [#completecareflow]

Complete a care flow explicitly (the outcome happened). Records manual completion provenance (who/why); a no-op when the care flow is already completed or stopped.

**Arguments**

| Argument | Type                     | Required | Description                              |
| -------- | ------------------------ | -------- | ---------------------------------------- |
| `input`  | `CompleteCareflowInput!` | Yes      | The details of the care flow to complete |

**Returns:** `EmptyPayload!`

**Example**

```graphql
mutation CompleteCareflow($input: CompleteCareflowInput!) {
  completeCareflow(input: $input) {
    code
    success
  }
}
```

Variables:

```json
{
  "input": {
    "careflow_id": "<string>"
  }
}
```

### `deletePathway` [#deletepathway]

Deletes a care flow.

**Arguments**

| Argument | Type                  | Required | Description                            |
| -------- | --------------------- | -------- | -------------------------------------- |
| `input`  | `DeletePathwayInput!` | Yes      | The details of the care flow to delete |

**Returns:** `EmptyPayload!`

**Example**

```graphql
mutation DeletePathway($input: DeletePathwayInput!) {
  deletePathway(input: $input) {
    code
    success
  }
}
```

Variables:

```json
{
  "input": {
    "pathway_id": "<string>"
  }
}
```

### `pauseCareFlow` [#pausecareflow]

Pauses a care flow.

**Arguments**

| Argument | Type                  | Required | Description                           |
| -------- | --------------------- | -------- | ------------------------------------- |
| `input`  | `PauseCareFlowInput!` | Yes      | The details of the care flow to pause |

**Returns:** `EmptyPayload!`

**Example**

```graphql
mutation PauseCareFlow($input: PauseCareFlowInput!) {
  pauseCareFlow(input: $input) {
    code
    success
  }
}
```

Variables:

```json
{
  "input": {
    "careflow_id": "<string>"
  }
}
```

### `saveBaselineInfo` [#savebaselineinfo]

Saves the baseline info for a care flow.

**Arguments**

| Argument | Type                     | Required | Description               |
| -------- | ------------------------ | -------- | ------------------------- |
| `input`  | `SaveBaselineInfoInput!` | Yes      | The baseline info to save |

**Returns:** `EmptyPayload!`

**Example**

```graphql
mutation SaveBaselineInfo($input: SaveBaselineInfoInput!) {
  saveBaselineInfo(input: $input) {
    code
    success
  }
}
```

Variables:

```json
{
  "input": {
    "baseline_info": [
      {
        "data_point_definition_id": "<string>",
        "value": "<string>"
      }
    ],
    "pathway_id": "<string>"
  }
}
```

### `startPathway` [#startpathway]

Starts a care flow for a patient from a care flow definition.

**Arguments**

| Argument | Type                 | Required | Description                           |
| -------- | -------------------- | -------- | ------------------------------------- |
| `input`  | `StartPathwayInput!` | Yes      | The details of the care flow to start |

**Returns:** `StartPathwayPayload!`

**Example**

```graphql
mutation StartPathway($input: StartPathwayInput!) {
  startPathway(input: $input) {
    code
    pathway_id
    stakeholders {
      clinical_app_role
      definition_id
      id
      label {
        en
      }
      release_id
      version
    }
    success
  }
}
```

Variables:

```json
{
  "input": {
    "pathway_definition_id": "<string>",
    "patient_id": "<string>"
  }
}
```

### `startPathwayWithPatientIdentifier` [#startpathwaywithpatientidentifier]

Starts a care flow for the patient matching a business identifier.

**Arguments**

| Argument | Type                                      | Required | Description                                                             |
| -------- | ----------------------------------------- | -------- | ----------------------------------------------------------------------- |
| `input`  | `StartPathwayWithPatientIdentifierInput!` | Yes      | The details of the care flow to start, including the patient identifier |

**Returns:** `StartPathwayWithPatientIdentifierPayload!`

**Example**

```graphql
mutation StartPathwayWithPatientIdentifier($input: StartPathwayWithPatientIdentifierInput!) {
  startPathwayWithPatientIdentifier(input: $input) {
    code
    pathway_id
    patient_id
    stakeholders {
      clinical_app_role
      definition_id
      id
      label {
        en
      }
      release_id
      version
    }
    success
  }
}
```

Variables:

```json
{
  "input": {
    "pathway_definition_id": "<string>",
    "patient_identifier": {
      "system": "<string>",
      "value": "<string>"
    }
  }
}
```

### `stopPathway` [#stoppathway]

Stops a care flow.

**Arguments**

| Argument | Type                | Required | Description                          |
| -------- | ------------------- | -------- | ------------------------------------ |
| `input`  | `StopPathwayInput!` | Yes      | The details of the care flow to stop |

**Returns:** `EmptyPayload!`

**Example**

```graphql
mutation StopPathway($input: StopPathwayInput!) {
  stopPathway(input: $input) {
    code
    success
  }
}
```

Variables:

```json
{
  "input": {
    "pathway_id": "<string>"
  }
}
```

### `unpauseCareFlow` [#unpausecareflow]

Resumes a paused care flow.

**Arguments**

| Argument | Type                    | Required | Description                             |
| -------- | ----------------------- | -------- | --------------------------------------- |
| `input`  | `UnpauseCareFlowInput!` | Yes      | The details of the care flow to unpause |

**Returns:** `EmptyPayload!`

**Example**

```graphql
mutation UnpauseCareFlow($input: UnpauseCareFlowInput!) {
  unpauseCareFlow(input: $input) {
    code
    success
  }
}
```

Variables:

```json
{
  "input": {
    "careflow_id": "<string>"
  }
}
```

### `updateBaselineInfo` [#updatebaselineinfo]

Updates the baseline info for a care flow.

**Arguments**

| Argument | Type                       | Required | Description                 |
| -------- | -------------------------- | -------- | --------------------------- |
| `input`  | `UpdateBaselineInfoInput!` | Yes      | The baseline info to update |

**Returns:** `EmptyPayload!`

**Example**

```graphql
mutation UpdateBaselineInfo($input: UpdateBaselineInfoInput!) {
  updateBaselineInfo(input: $input) {
    code
    success
  }
}
```

Variables:

```json
{
  "input": {
    "baseline_info": [
      {
        "data_point_definition_id": "<string>",
        "value": "<string>"
      }
    ],
    "pathway_id": "<string>"
  }
}
```