Making requests

Every call is a POST to one endpoint, with a bearer token:

https://network.neutron.health/graphql

The endpoint supports introspection, so you can point GraphiQL, Postman or your code generator at it to browse the schema or generate types.

A first call

curl https://network.neutron.health/graphql \
  --request POST \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "mutation ($patient: PatientInput!, $metadata: RequestMetadata!) { patient(patient: $patient, metadata: $metadata) { __typename ... on PatientPayload { patient { ... on Patient { id } } } } }",
    "variables": {
      "patient": { "id": "pat_01M3WQQHRB1T0K1469KD18BAWX" },
      "metadata": { "source": "DIRECT_API", "client": "acme-ehr" }
    }
  }'

The Sync patients guide has a small Node.js client that caches the machine token.

Metadata

Every mutation takes a metadata argument that says who is calling. Photon uses it for audit logs and support.

Field	Required	Description
`source`	Yes	The kind of caller. Backends use `DIRECT_API`.
`client`	No	Your application’s name, such as `"acme-ehr"`
`sourceVersion`	No	Your application’s version, such as `"2.4.1"`
`requestId`	No	Your own trace id for this call, to match it with your logs

source is one of DIRECT_API, WEB_APP, EMBEDDABLE_COMPONENT, MCP_CONNECTOR or LLM_AGENT.

Set client and requestId. When you contact support, they’re the fastest way for us to find your calls.

The result

Each mutation returns a union, so always select __typename and branch on it:

`__typename`	Meaning
`PatientPayload`, `PrescriptionPayload`, `OrderPayload`	The call ran. Read the record and its changes.
`AmbiguousPatientMatch`, `AmbiguousPrescriptionMatch`, `AmbiguousOrderMatch`	Photon couldn’t tell which existing record you meant, so nothing was saved. Resend with the `id` of one of the `candidates`.
`OperationError`	The call failed. `type` is `UNAUTHORIZED` (the token isn’t allowed to do this) or `UPSTREAM_SERVICE` (a Photon service failed: retry if `retryable` is true).

... on OperationError { type code message retryable }

See Errors for the full checklist.

Queries

Besides the three mutations, two queries read without changing anything.

`me`

Who the token authenticated as, and what it can do. Use it to check a token before you start.

query {
  me {
    __typename
    ... on MachineCaller { organizationId permissions }
    ... on ProviderCaller { organizationId permissions }
    ... on PatientCaller { patientId }
  }
}

A machine token is a MachineCaller, and a prescriber’s user token is a ProviderCaller. permissions lists its scopes.

`orders`

Your organization’s orders, newest first, drafts included. It needs read:order, and returns no orders without it.

query Orders($filter: OrdersFilterInput) {
  orders(filter: $filter, limit: 25) {
    __typename
    ... on OrdersPayload { orders { id state fulfillment { state } prescriptions { id treatment { name } } } }
    ... on AmbiguousPatientMatch { reason candidates { id firstName lastName dateOfBirth } }
    ... on OperationError { type code message }
  }
}

Argument	Description
`filter.patient`	Only this patient’s orders. Usually `{ id }`. Details that match several patients return `AmbiguousPatientMatch`. Details that match none return no orders.
`filter.state`	`DRAFT` for drafts only, `SUBMITTED` for sent orders that aren’t canceled, or `CANCELED`. Leave it out for drafts and every sent order, canceled ones included.
`limit`	Defaults to 25, and is capped at 100

orders is also the only place an order’s availablePharmacies are filled in.

ping is deprecated and will be removed after January 31, 2027. Use me instead.

Network

GraphQL

MCP

Webhooks

Making requests

A first call

Metadata

The result

Queries

`me`

`orders`

​A first call

​Metadata

​The result

​Queries

​me

​orders

A first call

Metadata

The result

Queries

`me`

`orders`