Blueprint AI · API Reference · v1

GraphQL API

A single GraphQL endpoint to integrate your application with the behavioral well-being platform: accounts, student data, AI analysis, risk intelligence, and notifications. This guide covers both authentication modes and every operation available to external consumers.

Protocol · GraphQL over HTTPS Subscriptions · WebSocket Format · JSON

Every interaction happens against a single GraphQL endpoint. Send a query, mutation, or subscription in the request body; the required credential type is indicated per operation with an authorization label.

Endpoint & transport

Your provider gives you the base URL for your environment. Replace <your-host> with that value.

Resource	Method	URL
GraphQL	POST	https://<your-host>/graphql
Subscriptions	WebSocket	wss://<your-host>/graphql
health	Query	public · returns `"ok"`

# Typical request
POST https://<your-host>/graphql
Content-Type: application/json
Authorization: Bearer <JWT>      # for user auth
X-Api-Key: sk-agth-…-<tenant>-v1   # or server-to-server auth

{ "query": "query { account { id agreement_free } }" }

Authentication

Each field declares which credential it accepts. There are two credentials and four access modes.

The two credentials

Credential	Header	For
JWT	Authorization: Bearer <token>	End users (web/mobile apps). Short-lived access token (~15 min) obtained via `login`/`signup` and renewable with `refreshToken`.
API Key	X-Api-Key: sk-agth-<32>-<tenant>-v1	Server-to-server integrations. The key is bound to a tenant; the tenant is inferred from the key itself. Generated with `createApiKey` and shown only once.

The four access modes

NO_USER

Public endpoints (login, signup). The request is rejected if it arrives already authenticated.

USER

Requires a valid JWT. The user and their tenant are extracted from the token.

API

Requires a valid API Key. Intended for server-to-server processes.

USER_OR_API

Accepts either credential: the API Key is tried first, falling back to the JWT.

Tenant isolation. Every operation is isolated to the credential's tenant. An API Key or a JWT can only see and modify data within its own tenant.

Session lifecycle (JWT)

login / signup return { token, refresh_token, user_id, tenant }.
The token expires after ~15 min; use refreshToken(refresh_token) to get a fresh pair without re-login (the refresh lasts ~30 days and rotates on each use).
logout(refresh_token) ends the session: it invalidates the access token and stops the refresh from rotating.
Reusing an already-rotated refresh invalidates the entire session (anti-theft protection).

Errors & conventions

Pagination: lists use cursors — page_size + page_token; the response includes the next token.
Deletion: most delete* operations are soft-deletes (they set a timestamp, they don't physically remove the record).
Amounts: the Int64 scalar represents the minor unit (e.g. cents).
Errors: returned in GraphQL's standard errors array. A downstream billing failure propagates as PAYMENT_UNAVAILABLE.

Auth & API Keys

Authentication, registration, and API key management.

Operation	Type	Auth	Arguments	Description
account	Query	USER_OR_API	—	Current account info (`id`, `agreement_free`).
login	Mut	NO_USER	email, password	Authenticates and returns an `AuthPayload` (token + refresh + user_id + tenant).
signup	Mut	NO_USER	email, password, name	Registers a user and returns a ready-to-use token pair.
refreshToken	Mut	NO_USER	refresh_token	Rotates the refresh and returns a new access + refresh.
logout	Mut	USER	refresh_token	Ends the current session and invalidates the access token.
validateToken	Mut	USER_OR_API	—	Validates the current credential and returns user/tenant info.
createApiKey	Mut	USER	—	Generates an API Key for the user. Shown only once.
validateApiKey	Mut	USER_OR_API	api_key	Validates an API Key and returns `{ valid, tenant, id, user }`.
revokeApiKey	Mut	USER	api_key	Revokes an API Key for the tenant (takes effect immediately).
signupCanvas	Mut	NO_USER	ltiToken	Onboards a school admin from a Canvas LTI 1.3 launch. Idempotent per deployment.

API Key format: sk-agth-<32 characters>-<tenant-uuid>-v1. The tenant is embedded in the key itself.

Payments & Billing

Internal balance, transactions, and payment methods (Stripe).

Operation	Type	Auth	Arguments	Description
getBalance	Query	USER_OR_API	user_id	Current balance (`current_balance`, `currency`).
listTransactions	Query	USER	user_id, page_size?, page_token?, start_time?, end_time?	Paginated list of transactions with time filters.
getTransaction	Query	USER	transaction_id	Detail of a single transaction.
getBillingSetting	Query	USER	—	The tenant's billing settings.
paymentAccount	Query	USER	—	The user's Stripe account.
updateBalance	Mut	USER	amount, metadata?	Adjusts the balance (credit/debit).
createBillingSetting	Mut	USER	auto_charge_amount?, paid_limit?, not_paid_limit?	Creates the billing settings.
updateBillingSetting	Mut	USER	auto_charge_amount, paid_limit, not_paid_limit	Replaces the billing settings.
createPaymentAccount	Mut	USER	email, id, name	Creates a Stripe Customer.
createCard	Mut	USER	cvc, exp_month, exp_year, number, token?	Attaches a card to the account.

Activity Ingestor

CRUD across 8 student behavioral-data domains. Uniform pattern per domain: get, list, create, update, delete · all USER_OR_API.

All list* operations accept user?, page_size?, page_token?. Each create* takes user (UUID) plus the domain-specific fields.

Domain	Operations	Representative create fields
Journal	getJournal · listJournals · createJournal · updateJournal · deleteJournal	title, content, mood?, tags?
RiskHistory	get · list · create · update · delete	risk_level, risk_type, flagged, severity, resolved_at?
SleepProfile	get · list · create · update · delete	hours_slept, quality, bed_time
WinGratitude	get · list · create · update · delete	type, title, category, shared_with?
TrustedPerson	get · list · create · update · delete	name, relationship, priority?, available?
MiniSurvey	get · list · create · update · delete	survey_type, responses[], score?, category?
SchoolInfo	get · list · create · update · delete	school_name, grade, subjects, grades[], attendance?
PersonalGoal	get · list · create · update · delete	title, status, target_date?, milestones[]

Analysis & Mood

Inference rules, the AI pipeline, analysis results, and emotional state.

Rules & inference

Operation	Type	Auth	Description
getRule · listRules	Query	USER_OR_API	Get/list inference rules.
runInference	Query	USER_OR_API	Runs the inference pipeline (consumes tokens/billing).
createRule · updateRule · deleteRule	Mut	USER_OR_API	Rule CRUD.
testModels	Mut	USER_OR_API	Test suite across a list of models.

Analysis & feedback

Operation	Type	Auth	Description
getAnalysis · listAnalyses	Query	USER_OR_API	Get/list analyses (filters: model, user, score, dates).
getAnalysisFromLLMS	Query	USER	Analyses run across multiple LLMs.
getFeedback · listFeedbacks	Query	USER	Human feedback on analyses.
createAnalysis	Mut	USER_OR_API	Creates an analysis (user, text, context, model?).
createAnalysisFromLLMS	Mut	USER_OR_API	Creates an analysis running several LLMs (consumes billing).
updateAnalysis · deleteAnalysis	Mut	USER	Partial update / delete.
createFeedback · updateFeedback · deleteFeedback	Mut	USER	Manage human feedback.

Mood

Operation	Type	Auth	Description
listMoods · listMoodCategories	Query	USER_OR_API	Mood catalog and categories.
getMood	Query	USER	Get a catalog mood by ID.
getMoodHistory · listMoodHistory	Query	USER_OR_API	Student mood history (filters: user, mood).
createMoodHistory · updateMoodHistory · deleteMoodHistory	Mut	USER_OR_API	Records mood entries (list of MoodEntry + note).
createMood · updateMood · deleteMood	Mut	USER	Manage the mood catalog (label, color, tips, video, category).

Chat (streaming)

Chat with the AI agent. Responses arrive streamed over a WebSocket subscription.

Flow: startSession → subscribe to chatMessages(session_id) → sendChatMessage. The agent's chunks are emitted over the subscription.

Operation	Type	Auth	Arguments	Description
startTest	Mut	USER_OR_API	user	Test session (not persisted).
startSession	Mut	USER_OR_API	user	Creates a real chat session.
sendChatMessage	Mut	USER_OR_API	message, session_id, user, metadata?	Sends a message; confirms immediately (the reply arrives over the subscription).
chatMessages	Sub	USER_OR_API	session_id	Stream of `ChatChunk` (chunk, is_last, inferenceOutput?). One connection per session.

WebSocket auth: when opening the connection (ConnectionInit), you can pass the API Key in the payload under the X-Api-Key key.

Knowledge Graph

The person's behavioral knowledge graph: identity, events, consent, snapshots, connectors, and trust.

Event ingestion and connector/consent administration are API (server-to-server). Reads and student-facing CRUD are USER_OR_API.

Person

Operation	Type	Auth	Description
person	Query	USER_OR_API	Get a person by ID.
persons	Query	API	Paginated list of persons.
resolvePerson	Mut	USER_OR_API	Resolves or creates a person from external IDs.
linkExternalID · updatePerson · deletePerson	Mut	USER_OR_API	Link external IDs, update, or soft-delete a person.
erasePerson	Mut	USER_OR_API	GDPR/FERPA erasure: removes all associated data; requires `reason`.

Behavioral events · consent · snapshots

Operation	Type	Auth	Description
eventTimeline · event	Query	API	A person's events (with filters) / by ID.
ingestEvent · batchIngestEvents	Mut	API	Event ingestion (trust + consent pipeline). The batch returns accepted/flagged/quarantined/rejected totals.
getConsent	Query	USER_OR_API	Get a consent by ID.
consents · checkConsent	Query	API	List consents / check whether consent exists for a category.
grantConsent · revokeConsent	Mut	API	Grant or revoke consent (FERPA/COPPA).
latestSnapshot	Query	USER_OR_API	A person's most recent snapshot.
snapshots	Query	API	Paginated snapshot history.
upsertSnapshot	Mut	USER_OR_API	Creates or updates a snapshot.

Connectors · trust · catalogs

Operation	Type	Auth	Description
getSourceStats	Query	USER_OR_API	Stats for a connector.
connectors · connector	Query	API	List / get connectors.
registerConnector · updateConnector · deleteConnector	Mut	API	Manage the connector registry.
evaluateTrust	Mut	USER_OR_API	Evaluates the composite trust score (user, source, event_type).
CommonQuestion · CopingTool (CRUD)	Mix	USER_OR_API	Auxiliary catalogs: get/list/create/update/delete.
TrustRelationship · Enrollment	Mix	USER_OR_API	The person's trust relationships and enrollments.

Metrics Engine

Tier 1 behavioral snapshots, explainability, and cohort metrics. Intended for dashboards and server-to-server pipelines.

Operation	Type	Auth	Arguments	Description
snapshot	Query	API	user	Most recent Tier 1 snapshot (mood, engagement, sleep, support, routine, trust).
metricFactors	Query	API	user, metricName	Breakdown of factors contributing to a metric.
cohortMetrics	Query	API	scopeType, scopeId?, metricNames, window="30d"	Aggregated cohort metrics (TENANT, ORGANIZATION, DISTRICT, CLASSROOM).
triggerTierARecompute	Mut	API	user, eventType, eventId	Real-time (risk-critical) recompute for a person.
triggerTierBRecompute	Mut	API	—	Batch recompute for all active persons in the tenant.

Intervention

Delivery of personalized interventions. A session advances through a linear FSM: EXPRESSION → SUPPORT → ACTION → FOLLOW_UP.

Operation	Type	Auth	Arguments	Description
intervention	Query	USER_OR_API	studentId	Deterministic intervention payload (pathway + supportBlocks + actionPayload).
createInterventionSession	Mut	USER_OR_API	studentId	Creates a session in the EXPRESSION state.
transitionInterventionState	Mut	USER_OR_API	sessionId, toState	Advances the FSM (fails if the transition breaks the guards).
recordInterventionOutcome	Mut	USER_OR_API	sessionId, studentId, toolId, moodDelta, …	Closes the session, records the outcome, and schedules the follow-up.

Pathway by risk level: 0–2 ROUTINE · 3 OBSERVATION · 4–6 IMMEDIATE_SAFETY (crisis, human-in-the-loop).

Notifications

Webhooks, emails, alert contacts, and risk alerts. All operations USER_OR_API.

Operation	Type	Arguments	Description
getWebhook · listWebhooks	Query	id / page_size?, page_token?	Tenant webhooks.
createWebhook · updateWebhook · deleteWebhook	Mut	name, url, events[], active	Webhook CRUD. Events are strings (e.g. `journal.created`, `risk.alerted`).
getEmailNotification · listEmailNotifications	Query	id / status_filter?, …	Email send history.
sendEmail	Mut	template_name, dynamic_data?, recipients?, from_name?	Sends a templated email. Returns notification_id + status.
getAlertContact · listAlertContacts	Query	id / —	Directory of alert contacts.
createAlertContact · updateAlertContact · deleteAlertContact	Mut	user, active	Manage alert contacts (they reference a tenant user).
getRiskAlert · listRiskAlerts	Query	id / status?	Risk alerts (pending, acknowledged).
acknowledgeRiskAlert	Mut	id, acknowledgedBy	Acknowledges a risk alert (closes the SLA).

Escalation Policy

Policies defining which roles and contacts are notified when a risk alert fires. All USER_OR_API.

Operation	Type	Arguments	Description
escalationPolicy	Query	id	Get a policy by ID.
escalationPolicies	Query	tenantId	List the tenant's active policies.
createEscalationPolicy · updateEscalationPolicy	Mut	targetRoles, contacts, ackTimeoutMinutes, fallbackPolicyId	Create/update a policy (fallback chain on ACK timeout).
deleteEscalationPolicy	Mut	id, tenantId	Soft-delete the policy.

Re-engagement Policy

One policy per tenant controlling post-intervention follow-up modals. USER_OR_API

Operation	Type	Arguments	Description
reengagementPolicy	Query	—	The tenant's policy (falls back to the system default if none is configured).
updateReengagementPolicy	Mut	frequencyCap24h, cooldownMinBetweenModals, criticalSuppressionFlag	Creates or replaces the policy.

LMS Connector

Data from external LMSes (Google Classroom, Canvas). All USER_OR_API; every read requires lms_type (e.g. "classroom", "canvas").

Operation	Type	Arguments	Description
listLMSCourses · getLMSCourse	Query	lms_type, external_id?	LMS courses.
getLMSCourseStudents	Query	lms_type, course_external_id	Students in a course.
listLMSAssignments · getLMSAssignment	Query	lms_type, course_external_id, assignment_external_id?	Course assignments.
listLMSSubmissions · getLMSStudentGrades	Query	lms_type, course_external_id, …	Submissions and grades.
listLMSEnrollments	Query	lms_type, course_external_id	Course enrollments.
getLMSConnectionStatus	Query	lms_type	OAuth connection status (status, expires_at).
registerLMSConnection	Mut	lms_type, client_id, client_secret, auth_code, …	Completes the OAuth flow to register the connection.
refreshLMSToken	Mut	lms_type	Refreshes the OAuth access token.

Manager

Action/operation registry.

Operation	Type	Auth	Arguments	Description
createAction	Mut	USER_OR_API	action, url, key	Registers a pending action/operation.

Blueprint AI GraphQL API consumer reference · v1 · Operations are isolated per tenant based on the credential. Replace <your-host> with your environment's base URL.