XP-Dev.com Documentation

Events API

This user guide only applies if your account and project is on our new platform, i.e. if your project's URL begins with https://<your-account>.xp-dev.com rather than https://xp-dev.com.

Each Event Object represents a certain action that took place to an entity (Story, Wiki page, Repository) in a project. It has the following attributes:

Attribute Description
userId ID of the user that generated this event
created Creation time in milliseconds since Epoch
url Full URL of the Event
eventType The nature of the event, one of:
  • Save - an entity was created
  • Update - an entity was updated
  • Delete - an entity was deleted
  • Push - a push event for a Git or Mercurial repository
  • Commit - a commit event for a Subversion repository
  • DeleteRef - a branch or tag was deleted from a Git or Mercurial repository
  • CreateRef - a branch or tag was created for a Git or Mercurial repository
project The project that this event was generated
details An array of EventField objects that describes the entity
objectType The type of entity - one of Story, Wiki, Task, TaskHour, Forum, ForumTopic, Blog, Comment, Bug, BugHour, Repository, Iteration, MergeRequest, TracChange
objectId The ID of the entity

Each EventField object has the following attributes:

Attribute Description
field Name of the field
oldValue Previous value of this field
newValue Current value of this field

List Events for your own User

GET request to https://<your-account>.xp-dev.com/api/v1/events:

curl https://<your-account>.xp-dev.com/api/v1/events

Responses will be a list of Event Objects:

[{
    "created":1450198465000,
    "userId":1,
    "url":"https://<your-account>.xp-dev.com/story/1",
    "eventType":"Save",
    "project":{"id":6},
    "details":[
        {"field":"description","oldValue":null,"newValue":"story description"},
        {"field":"iteration","oldValue":null,"newValue":"Project Week 2"}
    ],
    "objectType":"Story",
    "objectId":1
}]

By default, this will return the latest 30 events. You may retrieve further events from the past using the following HTTP parameters

  • size - how many events to return (maximum is 30)
  • offset - the n-th earliest event to return

If you'd like to retrieve 10 events past 50 events, you would call:

curl https://<your-account>.xp-dev.com/api/v1/events?size=10&offset=50

You can paginate the whole list of events using these two parameters

List Events for a Project

GET request to https://<your-account>.xp-dev.com/api/v1/events/project/<project ID>:

curl https://<your-account>.xp-dev.com/api/v1/events/project/453

Responses will be a list of Event Objects, and you can use the size and offset HTTP parameters to paginate across the whole event list as described above.

List Events for a specific Entity

GET request to https://<your-account>.xp-dev.com/api/v1/events/<object type>/<object ID>.

The object type is any one of the objectType values described in the table above in lower case. The object ID is the ID of the said object.

For example, to list the events of a Story that has an ID of 1:

curl https://<your-account>.xp-dev.com/api/v1/events/story/1

Responses will be a list of Event Objects, and you can use the size and offset HTTP parameters to paginate across the whole event list as described above.

Feel free to contact us if you need any assistance.