API Documentation

Hyperindex (hi, formerly Hypergoat) is GainForest's main AppView for the AT Protocol Hypersphere ecosystem. It indexes Lexicon-defined records and exposes them via a dynamically-generated GraphQL API.

Hypersphere ExplorerLexicon ReferenceFor AI Agents

Endpoints

HTTPPOST https://hypergoat-app-production.up.railway.app/graphql
WebSocketwss://hypergoat-app-production.up.railway.app/graphql
GraphiQLhttps://hypergoat-app-production.up.railway.app/graphiql

Protocol Details

HTTP/HTTPS

Standard GraphQL over HTTP. Send POST requests with JSON body containingqueryand optionalvariables.

WebSocket

Uses thegraphql-transport-wsprotocol for subscriptions. Connect with subprotocol header set accordingly.

Code Examples

javascript
1// Using fetch
2const response = await fetch("https://hypergoat-app-production.up.railway.app/graphql", {
3 method: "POST",
4 headers: {
5 "Content-Type": "application/json",
6 },
7 body: JSON.stringify({
8 query: `
9 query {
10 # Query your indexed records here
11 # Schema is dynamically generated from your lexicons
12 }
13 `,
14 variables: {}
15 })
16});
17
18const data = await response.json();
19console.log(data);
20
21// Using graphql-request
22import { GraphQLClient } from "graphql-request";
23
24const client = new GraphQLClient("https://hypergoat-app-production.up.railway.app/graphql");
25
26const query = `
27 query GetRecords {
28 # Your query here
29 }
30`;
31
32const result = await client.request(query);

WebSocket Protocol Reference

Hyperindex implements the graphql-transport-ws protocol. This is the modern standard for GraphQL subscriptions over WebSocket.

Connection Flow

  1. 1
    Connect - Open WebSocket with Sec-WebSocket-Protocol: graphql-transport-ws
  2. 2
    Initialize - Send {"type":"connection_init"}
  3. 3
    Acknowledge - Receive {"type":"connection_ack"}
  4. 4
    Subscribe - Send subscription with unique ID
  5. 5
    Receive - Get {"type":"next"} messages with data

Message Types

TypeDirectionDescription
connection_initClient → ServerInitialize connection
connection_ackServer → ClientConnection accepted
subscribeClient → ServerStart subscription
nextServer → ClientData payload
errorServer → ClientSubscription error
completeBothEnd subscription
ping/pongBothKeep-alive

Tips & Best Practices

  • Use GraphiQL — Explore the schema interactively at /graphiql
  • Schema introspection — Dynamically generated from uploaded lexicons
  • Relay pagination — Use first, after, last, before for cursors
  • Handle reconnection — Implement exponential backoff for WebSocket subscriptions