REST API Documentation
The primary interface into USERcycle is through events. As users perform key actions in your product,
you report them using the POST events method.
USERcycle uses these events to create person objects (your users) and automatically segments
them into various buckets (or cohorts). Cohorts help you measure "true" progress and
quickly identify hotspots in your application.
All events are processed asynchronously and in (near) realtime. USERcycle has a rich bi-directional
REST api that lets you query your data at any time. After all, it's your data and we believe you may
want to repurpose it for other uses.
- Ruby library (official)
- Python library (experimental & partially complete, user contributed)
Please send us your links to libraries you've created!
There are three types of resources in USERcycle: Events, People, and Cohorts.
|POST events||Used to record a new user event.|
|GET events/:id||Used to retrieve an event using it's unqiue identifier.|
|GET events||Used to find events.|
|GET people||Used to find users.|
|GET cohorts/daily/:date||Returns the daily cohorts metrics for the requested date range.|
|GET cohorts/weekly/:date||Returns the weekly cohorts metrics for the requested date range.|
|GET cohorts/monthly/:date||Returns the monthly cohorts metrics for the requested date range.|
All calls must include your API key in a X-Usercycle-API-Key request header.
For example, using the curl command line program to get a list of events:
curl -H 'X-Usercycle-API-Key: [your API key]' http://api.usercycle.com/api/v1/events.json
API methods provide JSON responses, served as application/json, encoded as UTF-8.
That media type should always be specified in the request’s Accept header. For example, again using cURL:
curl -H 'Accept: application/json' -H 'X-Usercycle-API-Key: [your API key]' \ http://api.usercycle.com/api/v1/events.json
Responses and Errors
All response codes are included in the HTTP Status response header. Possible status codes include:
- 200: Success (upon a successful GET, PUT, or DELETE request)
- 201: Created (upon a successful POST request)
- 400: Resource Invalid (improperly-formatted request)
- 401: Unauthorized (incorrect or missing authentication credentials)
- 404: Resource Not Found (requesting a non-existent person or other resource)
- 405: Method Not Allowed (e.g., trying to POST to a URL that responds only to GET)
- 406: Not Acceptable (server can’t satisfy the Accept header specified by the client)
- 500: Application Error