Skip to main content

๐Ÿ“š API Reference

This section documents the main Space Events and the matching client-side helpers in @graphprotocol/hypergraph and @graphprotocol/hypergraph-react.

โ„น๏ธ The SDK abstracts most serialization, encryption and validation. You'll rarely emit raw events yourselfโ€”Hooks and helper functions should cover 95 % of use-cases. Still, understanding their wire format helps with debugging and server integration.

Table of Contentsโ€‹


Event listโ€‹

EventHelperHTTP / WS PathAuthDescription
createSpacecreateSpace()/spaces (POST)SIWE + signatureBootstrap a new Space.
deleteSpacedeleteSpace()/spaces/:id (DELETE)adminSoft-delete a Space.
createInviteinviteToSpace()/spaces/:id/invites (POST)adminCreate an invitation to a Space.
acceptInviteacceptInvitation()/invites/:id/accept (POST)Invite signatureAccept an invitation & join a Space.
createSpaceInboxcreateInbox()/spaces/:id/inboxes (POST)adminCreate a new inbox in a Space.
sendUpdateinternal/updates (WS)memberSend a CRDT patch to peers.
sendCompactedUpdateinternal/updates (WS)memberSend a snapshot of the update log.

All payloads are JSON objects transported over either:

  • WebSocket โ€” default for low-latency real-time sync.
  • HTTP โ€” optional fallback for bootstrapping or server-to-server calls.

createSpaceโ€‹

MethodPOST /spaces (HTTP) or WebSocket event
AuthSigned with the creator's signature key + SIWE cookie
BodySee event schema below.
Success201 Created with { "spaceId": "โ€ฆ" }
Errors409 AlreadyExists, 401 Unauthorized, 422 InvalidSignature

Event Schemaโ€‹

The CreateSpaceEvent contains the initial parameters for a new space.

export const CreateSpaceEvent = Schema.Struct({
transaction: Schema.Struct({
type: Schema.Literal('create-space'),
id: Schema.String,
creatorAccountId: Schema.String,
}),
author: EventAuthor, // { accountId: string, signature: { hex: string, recovery: number } }
});

Request Exampleโ€‹

POST /spaces
{
"eventId": "6db7b5f0",
"spaceId": "efc45a11",
"transaction": {
"type": "create-space",
"id": "efc45a11",
"creatorAccountId": "did:pkh:eip155:1:0x123..."
},
"author": {
"accountId": "did:pkh:eip155:1:0x123...",
"signature": {
"hex": "0xabc...",
"recovery": 1
}
}
}

Response Exampleโ€‹

201 Created
{
"spaceId": "efc45a11"
}

deleteSpaceโ€‹

MethodDELETE /spaces/:id (HTTP) or WebSocket event
Authadmin role in the space
Success200 OK
Errors401 Unauthorized, 404 NotFound

Event Schemaโ€‹

The DeleteSpaceEvent marks a space for soft-deletion. It requires referencing the hash of the previous event to maintain chain integrity.

export const DeleteSpaceEvent = Schema.Struct({
transaction: Schema.Struct({
type: Schema.Literal('delete-space'),
id: Schema.String, // The ID of the space to delete
previousEventHash: Schema.String,
}),
author: EventAuthor,
});

createInviteโ€‹

MethodPOST /spaces/:id/invites (HTTP) or WebSocket event
Authadmin role in the space
Success201 Created
Errors401 Unauthorized, 404 NotFound, 422 Unprocessable Entity

Event Schemaโ€‹

The CreateInvitationEvent creates a new single-use invitation for an account to join the space.

export const CreateInvitationEvent = Schema.Struct({
transaction: Schema.Struct({
type: Schema.Literal('create-invitation'),
id: Schema.String, // The ID of the space
inviteeAccountId: Schema.String, // The account ID of the user being invited
previousEventHash: Schema.String,
}),
author: EventAuthor,
});

acceptInviteโ€‹

MethodPOST /invites/:id/accept (HTTP) or WebSocket event
AuthSignature from the invited account
Success200 OK
Errors401 Unauthorized, 404 NotFound

Event Schemaโ€‹

The AcceptInvitationEvent is created when a user accepts an invitation to join a space. This adds them to the member list.

export const AcceptInvitationEvent = Schema.Struct({
transaction: Schema.Struct({
type: Schema.Literal('accept-invitation'),
id: Schema.String, // The ID of the space
previousEventHash: Schema.String,
}),
author: EventAuthor, // The new member
});

createSpaceInboxโ€‹

MethodPOST /spaces/:id/inboxes (HTTP) or WebSocket event
Authadmin role in the space
Success201 Created
Errors401 Unauthorized, 404 NotFound

Event Schemaโ€‹

The CreateSpaceInboxEvent creates a new inbox within a space, which can be used for direct or broadcast messaging between members.

export const CreateSpaceInboxEvent = Schema.Struct({
transaction: Schema.Struct({
type: Schema.Literal('create-space-inbox'),
id: Schema.String, // The ID of the new inbox
spaceId: Schema.String, // The ID of the space
inboxId: Schema.String,
encryptionPublicKey: Schema.String,
secretKey: Schema.String, // Should be encrypted
isPublic: Schema.Boolean,
authPolicy: InboxSenderAuthPolicy, // 'all-members' | 'admins-only' | 'self-only'
previousEventHash: Schema.String,
}),
author: EventAuthor,
});

More endpointsโ€‹

The remaining endpoints (sendUpdate, sendCompactedUpdate) are used internally for state synchronization and are not typically called directly. For a deeper understanding of the entire event-sourcing model, you can refer to the type definitions exported from the SDK:

import { SpaceEvents } from '@graphprotocol/hypergraph';

// e.g., SpaceEvents.CreateSpaceEvent

Edit on GitHubโ€‹

โœ๏ธ Improve this page