> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyphaedb.com/llms.txt > Use this file to discover all available pages before exploring further. # Query cells against an explicit layer > Like recall, but against an explicit semantic layer (L0/L1/L2). Returns a JSON array of fully hydrated knowledge nodes in rank order. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/query openapi: 3.0.3 info: title: HyphaeDB REST API version: 1.0.0 description: >- The unary REST surface over the HyphaeDB internal service facade. JSON over HTTP/1.1; every endpoint is a thin translator onto the same facade that gRPC and MCP speak. `recall` and `query` return fully hydrated nodes in rank order (nearest-first); no similarity score rides the wire — the array order conveys the rank. All endpoints except `GET /healthz` require an API key supplied in the `x-hyphae-key` header. Errors use a uniform envelope: `{ "error": { "code": string, "message": string } }`. This document covers the unary REST endpoints only. The WebSocket gossip stream (`GET /v1/inbox`) and the MCP-over-HTTP endpoint (`POST /mcp`) are separate surfaces not described here, and `GET /openapi.json` serves this document itself. servers: - url: http://localhost:8080 description: Local HyphaeDB server security: - ApiKeyAuth: [] tags: - name: Memory description: Store and retrieve knowledge cells. - name: Sessions description: Open and close working sessions. - name: Beacons description: Standing interest beacons for gossip routing. - name: Inbox description: 'The gossip inbox: the unary work-cycle drain for non-resident agents.' - name: Scenes description: Scene listing, lookup, and consolidation. - name: Health description: Liveness probe. paths: /v1/query: post: tags: - Memory summary: Query cells against an explicit layer description: >- Like recall, but against an explicit semantic layer (L0/L1/L2). Returns a JSON array of fully hydrated knowledge nodes in rank order. operationId: query requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueryBody' responses: '200': description: Hydrated nodes in rank order (nearest-first). content: application/json: schema: type: array items: $ref: '#/components/schemas/KnowledgeNode' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '415': $ref: '#/components/responses/UnsupportedMediaType' '422': $ref: '#/components/responses/UnprocessableContent' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/Unavailable' '504': $ref: '#/components/responses/Timeout' components: schemas: QueryBody: type: object description: The body for `POST /v1/query`. required: - text - layer properties: text: type: string description: The query text to embed and query against. layer: $ref: '#/components/schemas/Layer' k: type: integer default: 10 minimum: 1 description: The maximum number of nodes to return. filter: $ref: '#/components/schemas/NodeFilter' KnowledgeNode: type: object description: A unit of knowledge as persisted and hydrated by recall/query. required: - id - tenant_id - embedding - node_type - cell_type - content - salience - source_agent - created_at - last_accessed - layer properties: id: type: string format: uuid tenant_id: type: string description: Always set; `default` in V1. embedding: type: array description: The cell's embedding vector. items: type: number format: float node_type: $ref: '#/components/schemas/NodeType' cell_type: $ref: '#/components/schemas/CellType' content: type: string scene_id: type: string format: uuid nullable: true description: The owning scene, if any. salience: type: number format: float minimum: 0 maximum: 1 description: Constrained to [0.0, 1.0]. source_agent: type: string description: The agent that produced this cell. created_at: type: string format: date-time last_accessed: type: string format: date-time layer: $ref: '#/components/schemas/Layer' superseded_by: type: string format: uuid nullable: true description: >- Supersession pointer; set once this cell has been abstracted into a higher-layer Pattern. `null` = live. Layer: type: string description: >- Semantic hierarchy. L0 = raw cells, L1 = scene centroids/patterns, L2 = architectural decisions/constraints. enum: - L0 - L1 - L2 NodeFilter: type: object description: >- Structural filter for recall/query. `source_agent` and `tenant_id` here are client-convenience filters; the enforced read boundary is applied separately by the server. properties: cell_types: type: array nullable: true description: Restrict to these cell types. items: $ref: '#/components/schemas/CellType' scene_id: type: string format: uuid nullable: true description: Restrict to a single scene. source_agent: type: string nullable: true description: Restrict to a single source agent. tenant_id: type: string nullable: true description: Convenience tenant filter (not the enforced boundary). NodeType: description: >- What a graph node represents. Serialized as an externally-tagged enum: the unit variant `Scene` is the bare string `"Scene"`; the data-carrying variants are single-key objects (`Cell`, `Agent`, `Beacon`). oneOf: - type: string enum: - Scene description: A scene node. - type: object description: A cell node carrying its cell type. additionalProperties: false required: - Cell properties: Cell: $ref: '#/components/schemas/CellType' - type: object description: An agent node carrying the agent id. additionalProperties: false required: - Agent properties: Agent: type: string - type: object description: A beacon node carrying its owner agent id. additionalProperties: false required: - Beacon properties: Beacon: type: object required: - owner properties: owner: type: string CellType: type: string description: >- The nine cell types the energy and promotion models are calibrated against. enum: - Decision - Constraint - Risk - Pattern - Lesson - Fact - Preference - Context - Task Error: type: object description: The uniform error envelope returned for every non-2xx response. required: - error properties: error: type: object required: - code - message properties: code: type: string description: A stable, machine-readable error code. enum: - not_found - validation - dimension_mismatch - unauthorized - forbidden - conflict - transaction - quota_exceeded - rate_limited - timeout - unavailable - storage - embedding - config - internal message: type: string description: >- A redaction-safe, human-readable description (never embeds secrets). responses: BadRequest: description: >- The request was malformed or failed validation (codes: `validation`, `dimension_mismatch`). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: 'Missing or invalid `x-hyphae-key` (code: `unauthorized`).' content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: 'Authenticated but not permitted (code: `forbidden`).' content: application/json: schema: $ref: '#/components/schemas/Error' UnsupportedMediaType: description: >- The request body was sent with a non-JSON `Content-Type` (code: `validation`). Send `Content-Type: application/json`. content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableContent: description: >- The JSON body parsed but did not match the expected shape — a missing required field or a wrong field type (code: `validation`). content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Quota exhausted or rate limited (codes: `quota_exceeded`, `rate_limited`). A `rate_limited` response sets the `Retry-After` header (in seconds). headers: Retry-After: description: Seconds to wait before retrying (only on `rate_limited`). schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: 'An internal error (codes: `embedding`, `config`, `internal`).' content: application/json: schema: $ref: '#/components/schemas/Error' Unavailable: description: 'A dependency was unavailable (codes: `unavailable`, `storage`).' content: application/json: schema: $ref: '#/components/schemas/Error' Timeout: description: 'The operation timed out (code: `timeout`).' content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-hyphae-key description: >- The API key issued for the calling agent. Required on every endpoint except `GET /healthz`. ````