GraphQL

The entire Circa API is mirrored as GraphQL. Authentication and versioning headers are identical to REST.

https://api.circa.ai/graphql

Authenticate with x-api-key, scope to a team with x-team-id, and (optionally) pin behavior with Circa-Version — exactly as for REST.

Schema overview

type Query {
  apiVersion: PublicApiVersion!

  # Basic
  me: PublicUser!
  teams: PublicTeamsPage!

  # Materials
  materials(input: PublicListInput): PublicMaterialsPage!
  material(id: ID!): PublicMaterial!
  materialProperty(materialId: ID!, propertyId: ID!): PublicMaterialProperty!

  # Processes
  processes(input: PublicListInput): PublicProcessesPage!
  process(id: ID!): PublicProcess!
  processImpact(processId: ID!, impactId: ID!): PublicProcessImpact!

  # Impact methods
  impactMethods: PublicImpactMethodsPage!
}

type Mutation {
  # Materials — pull individual properties
  pullProperties(input: PullPropertiesInput!): PullPropertiesResult!   # { materialId, propertyIds }

  # Processes — pull the batch size (inputs / outputs)
  pullProcess(input: PullProcessInput!): PullProcessResult!            # { processId, referenceProductIds }

  # Processes — pull impact values by characterization method
  pullImpacts(input: PullImpactsInput!): PullImpactsResult!            # { processId, characterizationFactorIds }
}

input PublicListInput {
  search: String
  limit: Int
  offset: Int
  pulled: Boolean   # restrict to records the active team has pulled
}

Pulling a material as a whole isn't a concept — you pull individual properties (rows inside a material). On the process side there are two separate pulls: batch size (pullProcess — reveals input/output exchanges) and impact values (pullImpacts — reveals characterization-method rows — the field is named characterizationFactorIds on the wire for parity with the library data model). See Queries for full input/return shapes and Mutations for the three pull operations.

Example

curl -s 'https://api.circa.ai/graphql' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: circa_live_xxx' \
  -H 'x-team-id: TEAM_ID_FROM_OVERVIEW' \
  -H 'Circa-Version: 2026-05-11.arrakis' \
  -d '{"query":"query { me { id email } materials(input: {limit: 5}) { items { id name } total } }"}'

Playground

Try queries interactively at the GraphQL playground. Paste these headers into the HTTP Headers tab at the bottom:

{
  "x-api-key": "circa_live_REPLACE_ME",
  "x-team-id": "4b6f9c28-6f4e-4e7f-a36d-2ff989045d10",
  "Circa-Version": "2026-05-11.arrakis"
}

GraphQL operations appear in your request log with method GQL and path /public/graphql#OperationName for easy filtering.