diff --git a/README.md b/README.md
index 06e0235..6f43830 100644
--- a/README.md
+++ b/README.md
@@ -1,57 +1,98 @@
 # tla-ths-api-spex
+
 wie man thesauruseintraege des berliner altaegyptischen woerterbuches abrufen und suchen soll
 
+
+## struktur einer response & error signaling
+
+Jede antwort hat eine kanonische form, die immer einen vollständigen `header` und ein 
+`result`-feld mit inhalt gemäß dem endpoint enthält. die (plain text) `description` im 
+header dient der anzeige für die user und ist bei einem status `error` obligatorisch.
+
+```json
+{
+  "header": {
+    "status": "success|error",
+    "code": …,
+    "description": "could not find entry with ID TL3NBDJXXZE7RKWNRVQS5TPSB",
+    "object_base_url": "http://tladev.bbaw.de/get/{id}"
+  },
+  "result":
+     // endpoint-spezifisch 
+}
+```
+
+
 ## endpunkte
 
 ### `/ths/get/<string:id>`
 
 - method: `GET`
 
-Man gibt die **26**-stellige (:point_up:) ID des thesauruseintrags an und bekommt eine `application/json` response folgender art:
+Man gibt die **26**-stellige (:point_up:) ID des thesauruseintrags an und bekommt eine 
+`application/json` response folgender art:
 
 ```json
-    {
-      "children": [],
-      "id": "CLJN6LLO5NDL7DY6HOP4XC4ELE",
-      "name": "Butler, Cuthbert",
-      "parents": [
-        "http://.../ths/get/OJDRAHAIX5BMND7OQH3TKTG4C4"
-      ],
-      "type": "person"
-    }
+{
+  "id": "CLJN6LLO5NDL7DY6HOP4XC4ELE",
+  "name": "Butler, Cuthbert",
+  "type": "person"
+}
 ```    
-    
-### `/ths/get/<string:id>/<string:key>`
+
+im falle eines fehlers steht im `result`-feld der response ein `null`. 
+
+
+### `/ths/get/<string:id>/<string:relation>`
 
 - method: `GET`
 
-Man gibt zusaetzlich zur **26**-stelligen (:point_up:) ID noch den namen der eigenschaft an, die man haben will. Moeglich sind `name`, `type`, `roots`, `parents`, `children`. Bei einem der letzten drei erhaelt man eine JSON response mit einer liste (ein eintrag kann mehrere wurzelelemente haben) von objekten mit jeweils `id`, `type` und `name` der verwandten thesauruseintraege. Wenn man `name` oder `type` anfragt, bekommt man eine `text/plain` response wo nur der gewuenschte inhalt drin steht.
+Man gibt zusaetzlich zur **26**-stelligen (:point_up:) ID noch den namen der beziehung 
+an, deren objekte man haben will. Moeglich sind `roots`, `parents` und `children`. Man erhält 
+eine JSON response mit einer liste (ein eintrag kann mehrere wurzelelemente haben) von URLs 
+von objekten. Wie im endpoint `search` kann der parameter `type` zum filtern angegeben werden.
+
+```json
+[
+  "CLJN6LLO5NDL7DY6HOP4XC4ELE",
+  "NDLBDCMPELEJNC4Y66FO5S4XHO",
+]
+```
+
+im falle eines fehlers steht im `result`-feld der response ein `null`.
+
 
 ### `/ths/search`
 
-- method: `POST`
+- method: `GET`
 
-Man sucht eintraege deren `name` feld mit dem angegebenen `term` beginnen. Das ergebnis ist eine liste von objekten, enthalten im `results`-feld der `application/json`-response. Die einzelnen results enthalten jeweils `id`, `name` und `type`.
+Man sucht eintraege deren `name` feld mit dem angegebenen `term` beginnen oder ihn 
+beinhalten. Das ergebnis ist eine liste von objekten, enthalten im `results`-feld der 
+`application/json`-response. Die einzelnen results enthalten jeweils `id`, `name` und 
+`type`.
 
-Im body koennen/muessen folgende parameter angegeben werden:
+Folgende parameter müssen oder können angegeben werden:
 
 |name|range|funktion|default|
 |---|---|---|---|
 |`term`|mindestens 2 zeichen lang|suchbegriff der im `name` vorkommen soll|**required**|
-|`search`|`{prefix\|contains}`|ob `term` am anfang von `name` oder irgendwo steht|`prefix`|
+|`mode`|`{prefix\|contains}`|ob `term` am anfang von `name` oder irgendwo steht|`prefix`|
 |`limit`|1-50, `int`|wie viele ergebnisse maximal|`50`|
-|`type`|einzelner string oder liste von strings|man kriegt nur ergebnisse, deren `type` im parameter genannt ist|
+|`offset`| |Index des ersten Items in den Gesamtergebnissen|`0`|
+|`type`|liste von strings|man kriegt nur ergebnisse, deren `type` im parameter kommagetrent genannt sind|`[]`|
 
-Die ergebnisse werden alphabetisch sortiert nach `name` und auf `limit` oder `50` stueck begrenzt. Beispiel:
+Die ergebnisse werden alphabetisch sortiert nach `name` und auf `limit` oder `50` stueck 
+begrenzt. Beispiel:
 
 ```bash
-    curl -XPOST -HContent-Type:application/json http://tladev.bbaw.de:5002/ths/search -d '{"term":"h","limit":5}'
+    curl http://tladev.bbaw.de:5002/ths/search?term=ha&limit=5
 ```
+
 ```json 
 {
-  "length": 5, 
-  "message": "God's in HIS heaven all's right with the earth", 
-  "result": [
+  "total": 23,  // lti!
+  "offset": 0,
+  "objects": [
     {
       "id": "7QGME3V2XZDN3IJKDWHZJWHEWU", 
       "name": "Haags Gemeentemuseum", 
@@ -78,22 +119,15 @@ Die ergebnisse werden alphabetisch sortiert nach `name` und auf `limit` oder `50
       "type": "bibliography"
     }
   ], 
-  "status": "success"
 }
 ```
 
-## error handling
 
-Der errorhandler gibt fehlermeldungen in folgender form aus:
+im falle eines fehlers steht im `result`-feld der response `{"total": 0, "offset": 0,"objects": []}`.
+
+Weitere Beispiele:
+
+```bash
+curl http://tladev.bbaw.de:5002/ths/search/?term=ha&type=person,location
 
-```json
-{
-  "error": {
-    "code": 404, 
-    "description": "<p>could not find entry with ID TL3NBDJXXZE7RKWNRVQS5TPSB</p>", 
-    "name": "Not Found", 
-    "type": "NotFound"
-  }, 
-  "status": "error"
-}
 ```