diff --git a/doc/api/README.md b/doc/api/README.md
index 0618db7e369..5a662cec43b 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -1,6 +1,6 @@
 # GitLab API
 
-All API requests require authentication. You need to pass a `private_token` parameter by url or header. You can find or reset your private token in your profile.
+All API requests require authentication. You need to pass a `private_token` parameter by url or header. If passed as header, the header name must be "PRIVATE-TOKEN" (capital and with dash instead of underscore). You can find or reset your private token in your profile.
 
 If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401:
 
@@ -18,6 +18,13 @@ Example of a valid API request:
 GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U
 ```
 
+Example for a valid API request using curl and authentication via header:
+
+```
+curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/projects"
+```
+
+
 The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL.
 
 #### Pagination
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 2e13ccb88d4..1d6afbc2039 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -65,7 +65,8 @@ Return values:
 
 ### Get single project
 
-Get a specific project, identified by project ID, which is owned by the authentication user.
+Get a specific project, identified by project ID or NAME, which is owned by the authentication user.
+Currently namespaced projects cannot retrieved by name.
 
 ```
 GET /projects/:id
@@ -73,7 +74,7 @@ GET /projects/:id
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 
 ```json
 {
@@ -132,7 +133,20 @@ Return values:
 + `404 Not Found` if something else fails
 
 
-### List project members
+## Project access levels
+
+The project access levels are defined in the `user_project` class. Currently, 4 
+levels are recoginized:
+
+```
+  GUEST     = 10
+  REPORTER  = 20
+  DEVELOPER = 30
+  MASTER    = 40
+```
+
+
+## List project team members
 
 Get a list of project team members.
 
@@ -142,7 +156,7 @@ GET /projects/:id/members
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `query`         - Query string
 
 Return Values:
@@ -163,7 +177,7 @@ GET /projects/:id/members/:user_id
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `user_id` (required) - The ID of a user
 
 ```json
@@ -196,7 +210,7 @@ POST /projects/:id/members
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `user_id` (required) - The ID of a user to add
 + `access_level` (required) - Project access level
 
@@ -219,7 +233,7 @@ PUT /projects/:id/members/:user_id
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `user_id` (required) - The ID of a team member
 + `access_level` (required) - Project access level
 
@@ -242,7 +256,7 @@ DELETE /projects/:id/members/:user_id
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `user_id` (required) - The ID of a team member
 
 Return Values:
@@ -269,7 +283,7 @@ GET /projects/:id/hooks
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 
 Return values:
 
@@ -288,7 +302,7 @@ GET /projects/:id/hooks/:hook_id
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `hook_id` (required) - The ID of a project hook
 
 ```json
@@ -315,7 +329,7 @@ POST /projects/:id/hooks
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `url` (required) - The hook URL
 
 Return values:
@@ -336,7 +350,7 @@ PUT /projects/:id/hooks/:hook_id
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `hook_id` (required) - The ID of a project hook
 + `url` (required) - The hook URL
 
@@ -359,7 +373,7 @@ DELETE /projects/:id/hooks/:hook_id
 
 Parameters:
 
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `hook_id` (required) - The ID of hook to delete
 
 Return values: