GraphQL API
Substrate provides a GraphQL API powered by Apollo Server. This guide explains how to use and extend the GraphQL API.
Overview
The GraphQL API is available at /api/graphql and provides:
- Type-safe queries and mutations - Full GraphQL schema with TypeScript types
- Authentication integration - Automatic session handling via next-auth
- Authorization support - Role-based access control with OAuth scope preparation
- Introspection - Full schema introspection in development mode
Getting Started
Accessing the API
The GraphQL endpoint is available at /api/graphql. In development, visit this URL in your browser to access Apollo Sandbox for interactive queries.
Schema Location
GraphQL schemas are defined in .graphql files located at:
packages/shared-graphql/src/schemas/schema.graphql- Base typespackages/shared-graphql/src/schemas/user/schema.graphql- User domainpackages/shared-graphql/src/schemas/org/schema.graphql- Organization domain
Apollo Client
The app includes Apollo Client configured for use in React components. See apps/web/src/lib/apollo/ for the client configuration.
Available Operations
Queries
| Query | Description | Auth Required |
|---|---|---|
hello | Test query | No |
me | Current user's auth info | No |
profile(authUserId) | Get profile by auth user ID | Yes |
myProfile | Current user's profile | Yes |
Mutations
| Mutation | Description | Auth Required |
|---|---|---|
createProfile(input) | Create a new profile | Yes |
updateProfile(authUserId, input) | Update existing profile | Yes |
addOrganizationMember(organizationId, input) | Add organization member | Yes (admin/owner) |
Schema Types
See the Schema Reference for complete type definitions, or explore the schemas directly in packages/shared-graphql/src/schemas/.