ReferenceAPI Reference

API Reference

Complete API reference for HeySummon v4.

Consumer API (v1)

These endpoints are used by AI agents to submit help requests and exchange encrypted messages.

Submit Help Request

POST /api/v1/help
FieldTypeRequiredDescription
apiKeystring✅API key (hs_ for consumers)
consumerSignPubKeystring✅Ed25519 signing public key (PEM)
consumerEncryptPubKeystring✅X25519 encryption public key (PEM)
messagesarray✅Conversation messages (last 10)
questionstring❌Specific question for expert
plaintextstring❌Plaintext version of the message (for simple reply flows)

Response: 201 Created

{
  "requestId": "clxyz...",
  "refCode": "HS-AB12",
  "status": "pending",
  "expiresAt": "2026-02-23T00:00:00.000Z"
}

Side effect: Publishes new_request event to Mercure topic /hitlaas/providers/{userId}.

Lookup by Reference Code

GET /api/v1/requests/by-ref/{refCode}

Headers: x-api-key: hs_...

Look up a request by its human-readable reference code (e.g., HS-AB12). Returns request details including responseCount.

Key Exchange (Provider → Consumer)

POST /api/v1/key-exchange/:requestId

Headers: x-api-key: hs_prov_...

FieldTypeRequiredDescription
providerSignPubKeystring✅Provider’s Ed25519 signing public key (PEM)
providerEncryptPubKeystring✅Provider’s X25519 encryption public key (PEM)

After key exchange, both parties can compute the shared DH secret independently.

Send Message

POST /api/v1/message/:requestId

Headers: x-api-key: hs_... or hs_prov_...

Encrypted message:

FieldTypeRequiredDescription
rolestring✅consumer or provider
encryptedobject✅*{ iv, ciphertext, tag, ephemeralPublicKey } (all base64)
signaturestring✅*Ed25519 signature (base64)
messageIdstring❌UUID (auto-generated if omitted)

Plaintext message:

FieldTypeRequiredDescription
rolestring✅consumer or provider
plaintextstring✅*Plain text message content

* Either encrypted + signature OR plaintext must be provided.

Side effect: Publishes new_message event to Mercure topic /hitlaas/requests/{requestId}.

Providers can send multiple messages per request. Each triggers a new Mercure event.

Get Messages

GET /api/v1/messages/:requestId

Headers: x-api-key: hs_...

Returns all messages for the conversation (encrypted blobs and/or plaintext + metadata). Includes responseCount.

Close Conversation

POST /api/v1/close/:requestId

Headers: x-api-key: hs_...

Closes the conversation. Requests auto-expire after 72 hours.

Side effect: Publishes request_closed event to Mercure.

Poll for Status (Legacy)

GET /api/v1/help/:requestId

Returns request status. Prefer Mercure SSE for realtime updates.

Realtime Events (Mercure)

HeySummon publishes events via Mercure Hub using Server-Sent Events (SSE).

Subscribe to Provider Events

curl -sN "http://localhost:3100/.well-known/mercure?topic=/hitlaas/providers/{userId}"

Subscribe to Request Events

curl -sN "http://localhost:3100/.well-known/mercure?topic=/hitlaas/requests/{requestId}"

Event Types

TypeTopicPayload
new_request/hitlaas/providers/{id}{ type, refCode, question }
new_message/hitlaas/requests/{id}{ type, role, messageId }
key_exchange/hitlaas/requests/{id}{ type, refCode }
request_closed/hitlaas/requests/{id}{ type, refCode }

Key Validation

Key typePrefixUsed by
Consumer API keyhs_AI agents submitting requests
Provider API keyhs_prov_Human experts responding to requests

Keys are validated on every API call. Invalid prefixes return 401 Unauthorized.

Provider API

These endpoints require an authenticated session (OAuth).

List Requests

GET /api/requests

Returns requests with response counts.

View Request

GET /api/requests/:id

List API Keys

GET /api/keys

Create API Key

POST /api/keys

Health Check

GET /api/health
{
  "status": "ok",
  "version": "0.1.0",
  "timestamp": "2026-02-20T00:00:00.000Z"
}

Summary Table

MethodEndpointAuthDescription
POST/api/v1/helpAPI key (hs_)Submit help request
GET/api/v1/requests/by-ref/{refCode}API keyLookup request by reference code
POST/api/v1/key-exchange/:idAPI key (hs_prov_)Exchange DH public keys
POST/api/v1/message/:idAPI keySend message (encrypted or plaintext)
GET/api/v1/messages/:idAPI keyGet conversation messages
POST/api/v1/close/:idAPI keyClose conversation
GET/api/v1/help/:idNone*Poll status (legacy)
GET/api/requestsSessionList requests (provider)
GET/api/requests/:idSessionView request (provider)
GET/api/keysSessionList API keys
POST/api/keysSessionCreate API key
GET/api/healthNoneHealth check

* Polling without x-api-key header logs a warning.

Rate Limits

ScopeLimit
General60 req/min per IP
API v130 req/min per IP
Polling (legacy)20 req/min per IP

Exceeded: 429 Too Many Requests with Retry-After: 60.

ContributingChangelog