first commit

docs/references/planview-rest-api-v2.md

@@ -0,0 +1,38 @@
+# Planview Adaptive Work — REST API V2 (reference)
+
+Official guide: [REST API Guide Version 2](https://success.planview.com/Planview_AdaptiveWork/API/REST_API_Guide_Version_2)
+
+Live operation/type reference: [https://api.clarizen.com/V2.0/services/](https://api.clarizen.com/V2.0/services/) (requires `Accept: text/html` or API auth)
+
+## Auth flow (password)
+
+1. `POST authentication/getServerDefinition` → `serverLocation` (org datacenter, e.g. `https://api2.clarizen.com/V2.0/services`)
+2. `POST authentication/login` on that base URL → `sessionId`
+3. Subsequent calls: `Authorization: Session {sessionId}`
+
+API keys use `Authorization: ApiKey {token}` on the org’s API host (often discoverable via `getServerDefinition` with the key).
+
+## Entity CRUD
+
+`/V2.0/services/data/objects/{typeName}` — PUT create  
+`/V2.0/services/data/objects/{typeName}/{id}` — GET retrieve, POST update, DELETE remove
+
+Field selection on GET: `?fields=CreatedOn,CreatedBy.Name`
+
+## Queries
+
+- `data/entityQuery` — structured `where` (`Condition`), `orders`, `paging` (`from` / `limit`)
+- `data/query` — CZQL (`?q=SELECT ...`)
+- Conditions may include `_type: 'Compare'` (optional; see guide examples)
+
+## Operations notes
+
+- Prefer `Accept-Encoding: gzip` on requests
+- Errors: HTTP 500 body with `errorCode`, `message`, `referenceId`
+- Session idle timeout ~10 minutes; max 2 concurrent sessions per user
+- Rate limit: ~25 requests/second per organization (bulk inner calls count separately)
+
+## Related Planview articles (same site)
+
+- [API Keys Support](https://success.planview.com/Planview_AdaptiveWork/API/API_Keys_Support) (sibling under API)
+- CZQL — linked from the v2 guide “New Features” section