Initial GeoIntel V1 foundation

contracts/api/response-envelope.md

@@ -0,0 +1,53 @@
+# API Response and Error Contract
+
+## Standard error
+
+All API errors must use:
+
+```json
+{
+  "error": {
+    "code": "STRING_CODE",
+    "message": "Human readable message.",
+    "details": {}
+  }
+}
+```
+
+## Job response
+
+Long-running operations return:
+
+```json
+{
+  "job_id": "uuid",
+  "analysis_run_id": "uuid",
+  "status": "queued",
+  "status_url": "/analysis-runs/{id}"
+}
+```
+
+## Resource metadata
+
+Resources should include:
+
+```json
+{
+  "id": "uuid",
+  "created_at": "ISO-8601",
+  "updated_at": "ISO-8601"
+}
+```
+
+## Pagination
+
+List endpoints use:
+
+```json
+{
+  "items": [],
+  "total": 0,
+  "limit": 50,
+  "offset": 0
+}
+```