01 — HTTP wire

Status: Draft (protocol v1)
Applies to: Compliance Level 1+

Base path

Adapters mount under a configurable base path. Unless otherwise noted, examples use /mesh. Implementations MUST support remapping the base path.

Routes (core — L1)

Method	Path	Purpose
GET	/{base}/:entity	List read (or empty list selection)
GET	/{base}/:entity/:id	Point read
POST	/{base}	Complex query in JSON body
PUT	/{base}/:entity/:id	Point read with PUT transport (same query headers as GET)

:entity is the MeshQL entity key (e.g. user). :id is the resource primary key as a path segment (string; implementations MAY coerce numerics when talking to storage).

Core write mutations (create/update/delete) are not part of protocol v1. DELETE SHOULD return 405 until a mutation profile is specified.

Routes (integrity — L3)

Method	Path	Purpose
POST	/{base}/auth	Login — returns signing token material
POST	/{base}/logout	Revoke session

Routes (uploads — L4)

Method	Path	Purpose
POST	/{base}/:entity/:id/:field	Multipart file upload (attach to existing)
POST	/{base}/:entity	Multipart upload (create)

See 07 — Uploads.

Headers (GET / PUT)

Header	Required	Description
X-Mesh-Query	Yes	Base64-encoded query payload (UTF-8). Padding MAY be present.
X-Mesh-Format	No	json (default) or ql
X-Mesh-Version	No	Protocol version; default 1
X-Mesh-Signature	L3	sha256= + hex HMAC over the exact X-Mesh-Query header value
X-Mesh-Token	L3	Opaque wire token from auth

X-Mesh-Query MUST NOT be passed as a URL query parameter for L1 compliance.

Encoding

1. Serialize the query as UTF-8 text (JSON string or QL string).
2. Base64-encode (standard alphabet). Strip newlines when transmitting.
3. Place the result in X-Mesh-Query.

POST /{base} body

{
  "query": "{ user { id name } }",
  "format": "ql"
}

Field	Required	Notes
query	Yes	Raw query string (not base64)
format	No	Defaults to ql

Content-Type: application/json.

Successful response

• Status 200
• Body: JSON object or array shaped per the selection (see 04 — Shaper)
• Point reads typically return a single object (or empty object / 404 — implementation MAY choose; the TypeScript reference returns {} for missing Prisma rows). Document behavior.

Error response

Status codes:

Condition	Status	error field
Missing / invalid transport (X-Mesh-Query)	400	TransportError
Unknown entity/field/join or invalid query	400	ValidationError
Integrity failure	401 / 403	IntegrityError (L3)
Resolver failure	500	ResolverError
Unexpected failure	500	InternalError

Body shape:

{
  "error": "ValidationError",
  "message": "Field 'secret' not found on entity 'user'"
}

Implementations MUST use JSON error bodies on failure for these routes. Additional fields (e.g. requestId) are allowed.

CORS / content types

Not normative. Implementations serving browsers SHOULD allow the X-Mesh-* request headers.