diff --git a/docs/openapi.yaml b/docs/openapi.yaml
new file mode 100644
index 00000000..1e58d88d
--- /dev/null
+++ b/docs/openapi.yaml
@@ -0,0 +1,102 @@
+openapi: 3.0.0
+info:
+  title: Engram Miner API
+  description: API specification for Engram miner HTTP endpoints
+  version: 1.0.0
+servers:
+  - url: http://localhost:8000
+    description: Local development server
+
+components:
+  securitySchemes:
+    Sr25519Signature:
+      type: apiKey
+      in: header
+      name: X-Sr25519-Signature
+      description: Sr25519 signed challenge header for authentication
+
+paths:
+  /ingest:
+    post:
+      summary: Ingest data into the Engram network
+      security:
+        - Sr25519Signature: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                data:
+                  type: string
+                  description: Data to ingest
+                namespace:
+                  type: string
+                  description: Optional namespace for private data
+              required:
+                - data
+      responses:
+        '200':
+          description: Data ingested successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  message:
+                    type: string
+        '401':
+          description: Unauthorized - invalid signature
+  
+  /query:
+    post:
+      summary: Query data from the Engram network
+      security:
+        - Sr25519Signature: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                query:
+                  type: string
+                  description: Query string
+                limit:
+                  type: integer
+                  description: Maximum number of results
+              required:
+                - query
+      responses:
+        '200':
+          description: Query results
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                    items:
+                      type: object
+        '401':
+          description: Unauthorized - invalid signature
+
+  /health:
+    get:
+      summary: Health check endpoint
+      responses:
+        '200':
+          description: Service is healthy
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: healthy