REST API Documentation

Introduction

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.

Ready-made Libraries

Please send us your links to libraries you've created!

REST Resources

There are three types of resources in USERcycle: Events, People, and Cohorts.


Events

Events are used to record user actions in your web application.
Events contain a user identifer, an action and an arbitrary list of properties.

Resource Description
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.

People

People are used to identify users in your web application.
They are automatically created when you send events and contain an arbitrary list of properties.

Resource Description
GET people Used to find users.

Cohorts

Cohorts are used to group your users and track their actions over time.
There are 3 types of cohort intervals - daily, weekly, and monthly.

Resource Description
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.

Authentication

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

Format

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