generated: '2026-08-14'
method: searched
source: docs.photon.health + graphql/photon-clinical-api-schema.json + openapi/photon-website-api-openapi.json + live header probes
surfaces:
  note: >-
    Photon runs TWO unrelated HTTP surfaces with different conventions. Do not
    apply one's rules to the other.
  clinical_api:
    style: graphql
    host: https://clinical-api.photon.health
    auth: OAuth2 client-credentials (Auth0) Bearer
    contract: graphql/photon-clinical-api-schema.json
  website_api:
    style: rest
    host: https://photonhealth.com
    auth: onboarding lead token (apiKey header or cookie); anonymous also permitted
    contract: openapi/photon-website-api-openapi.json
    scope: onboarding funnel + newsletter signup only
content_negotiation:
  markdown_twins: true
  request: 'Accept: text/markdown'
  alias: append .md to any page URL (/index.html.md for the homepage)
  response_headers: [content-type text/markdown, content-signal, x-markdown-tokens]
  scope: photonhealth.com marketing pages and docs.photon.health pages
  ref: agentic-access/photon-agentic-access.yml
discovery:
  api_catalog: https://photonhealth.com/.well-known/api-catalog
  link_headers: true
  note: RFC 9727 linkset plus RFC 8288 Link headers on every response; see conformance/photon-conformance.yml.
api_style: graphql
transport:
  endpoint: POST https://clinical-api.photon.health/graphql
  sandbox_endpoint: POST https://clinical-api.neutron.health/graphql
  content_type: application/json
authentication:
  style: oauth2-client-credentials
  header: 'Authorization: Bearer <access_token>'
  provider: Auth0
  ref: authentication/photon-authentication.yml
identifiers:
  style: prefixed-ids
  note: Entities use type-prefixed opaque IDs.
  examples:
  - pat_ (Patient, e.g. pat_123)
  - phr_ (Pharmacy, e.g. phr_01GA9HPV354YPQATCPCCE8D9N3)
  format: ULID-style suffix on several resource prefixes
pagination:
  style: argument-based
  note: >-
    List queries (patients, orders, invites, users, clients) accept filter and
    limit/offset-style arguments defined per field in the schema; there is no
    global Relay cursor connection wrapper across all lists.
error_envelope:
  style: graphql-errors
  fields: [message, locations, path, extensions]
  ref: errors/photon-error-codes.yml
idempotency:
  supported: false
  note: >-
    No idempotency-key header or parameter exists on either surface. Re-checked
    2026-08-14: the GraphQL schema declares no idempotency argument on any of the
    26 Mutation fields, and the website OpenAPI declares no idempotency header on
    any of its 5 write operations. The closest thing is the create-OR-RESUME
    semantic on createOrResumeOnboardingSession, which limits duplicate leads but
    is not a general idempotency contract. No Idempotency pointer is emitted.
events:
  style: webhooks
  format: CloudEvents 1.0
  ref: asyncapi/photon-order-events-webhooks.yml
rate_limiting:
  documented: false
  note: No published rate-limit policy or response headers were found; expect gateway 429 under load.
cross_references:
  authentication: authentication/photon-authentication.yml
  scopes: scopes/photon-scopes.yml
  errors: errors/photon-error-codes.yml
  lifecycle: lifecycle/photon-lifecycle.yml
  data_model: data-model/photon-data-model.yml