General API notes

All API calls (currently) permit only GET requests.

A trailing slash is optional on all API endpoints. There is no difference between using one and not using one.

Responses can be served as application/json or text/html as per the accept header. If the request is made in “text/html” then it will return the html content otherwise it will return the json content (unless JSONP is explicitly requested, in which case datagrepper returns the appropriate application/javascript).

/v2/search

The /v2/search endpoint returns lists of messages.

Response format

Sample response:

{
  "arguments": {
    "page": 1,
    "rows_per_page": 20,
    ...
  },
  "count": 1,
  "pages": 42,
  "raw_messages": [
    {
      "body": {
        ...
      },
      "headers": {
        ...
      },
      "id": "...",
      "topic": "org.fedoraproject.prod.sample"
    },
    ...
  ],
  "total": 851
}

The arguments item in the root dictionary contains all possible arguments, and displays the value used (the default if the argument was not provided).

Time arguments

Below is a table describing what timeframe messages are received from depending on what combination of time options you provide.

delta	start	end	Message timeframe
no	no	no	last rows_per_page items
yes	no	no	last delta seconds
no	yes	no	from start until now
yes	yes	no	from start until delta seconds from start
no	no	yes	the 600 seconds before end
yes	no	yes	the delta seconds before end
no	yes	yes	between start and end
yes	yes	yes	between start and end (delta is ignored)

delta

Return results from the last delta seconds.

Default: None

start

Return results starting at time start (in UNIX time).

Default: None or (end minus delta)

end

Return results ending at time end (in UNIX time).

Default: None or current

Filter arguments

user

FAS user to query for.

This argument can be provided multiple times; returns messages referring to any listed user.

Default: all users

package

Fedora package to query for.

This argument can be provided multiple times; returns messages referring to any listed package.

Default: all packages

category

Category to query for.

In fedmsg, a category is what service emitted the message, e.g. git, bodhi, or wiki. The category is usually the third or fourth part of the topic.

This argument can be provided multiple times; returns messages referring to any listed category.

Default: all categories

topic

Topic to query for.

In fedmsg, a topic is a full reverse-domain description of the type of message, such as org.fedoraproject.prod.git.receive.

This argument can be provided multiple times; returns messages referring to any listed topic.

Default: all topics

contains

Keyword to search in the messages.

Sometime one knows only a part of a message, this would allow retrieving all the messages containing that part.

This argument can be provided multiple times; returns messages referring to any listed topic.

Default: all messages

not_user

FAS users to exempt from query.

This argument can be provided multiple times; returns only messages that do not refer to any listed user.

Default: no users

not_package

Fedora package to exempt from query.

This argument can be provided multiple times; returns only messages that do not refer to any listed package.

Default: no packages

not_category

Category to exempt from query.

In fedmsg, a category is what service emitted the message, e.g. git, bodhi, or wiki. The category is usually the third or fourth part of the topic.

This argument can be provided multiple times; returns only messages that do not fall under the listed categories.

Default: no categories

not_topic

Topic to exempt from query.

In fedmsg, a topic is a full reverse-domain description of the type of message, such as org.fedoraproject.prod.git.receive.

This argument can be provided multiple times; returns only messages that do are not marked with the listed topics.

Default: no topics

Pagination arguments

page

Which page to return. Must be greater than 0.

Default: 1

rows_per_page

The number of messages to return for each page. Must be less than or equal to 100.

Default: 20

order

The “order” in which messages should be returned. Must be one of either “asc” or “desc”. “asc” means ascending, i.e. from oldest to newest. “desc” means descending, i.e. from newest to oldest.

Default: “desc”

Formatting arguments

callback

To be specified when querying datagrepper via JavaScript/ajax, it will return a “jsonp” output with the MIME type ‘application/javascript’ instead of the traditionnal “json”.

Default: None

meta

Argument to specify what meta information to return with the raw message from fedmsg. Options are: summary, text, app_icon, agent_avatar, url, usernames, packages, containers, modules, flatpaks, and date.

Default: None

chrome

“chrome” decides whether the messages should be displayed with html boiler-plate or not. Must be one of either “true” or “false”. “true” means with boiler-plate and “false” implies without it.

Default: true

size

Argument need to be specified if you want to receive different kinds of message cards. Options are: small, medium, large, and extra-large. "small" contains link and title. "medium" contains link, title, icon and subtitle. "large" contains link, title, icon, subtitle, secondary_icon and datetime. "extra-large" contains those of “large”, but it also displays the full JSON body of the raw message.

Default: large

/v2/id

Returns the message by the particular message-id given by the user.

Formatting arguments

chrome

Same as that of /v2/search

size

Same as that of /v2/search