diff --git a/README.md b/README.md
index a28ec8402..5a05cdb81 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,42 @@
+# PyMISP - Python Library to access MISP
+
 PyMISP is a Python library to access [MISP](https://github.com/MISP/MISP) platforms via their REST API.
 
-Requirements
-------------
+PyMISP allows you to fetch events, add or update events/attributes, add or update samples or search for attributes.
+
+## Requirements
 
  * [requests](http://docs.python-requests.org)
 
-Install
--------
+## Install
 
+~~~~
 python setup.py install
+~~~~
 
-Example
--------
+## Samples and how to use PyMISP 
 
-An example to copy events between MISP instances is included in examples/
+Various examples and samples scripts are in the [examples/](examples/) directory.
+
+In the examples directory, you will need to change the keys.py.sample to enter your MISP url and API key.
+
+~~~~
+cd examples
+cp keys.py.sample keys.py
+vim keys.py
+~~~~
+
+The API key of MISP is available in the Automation section of the MISP web interface.
+
+To test if your URL and API keys are correct, you can test with examples/last.py to
+fetch the last 10 events published.
+
+~~~~
+cd examples
+python last.py -l 10
+~~~~
 
-Documentation
--------------
+## Documentation
 
 [PyMISP API documentation is available](http://www.circl.lu/assets/files/PyMISP.pdf).