API Endpoints

The Atomx API is what allows you to create, modify and delete things in Atomx. The best example on how to use the API is the Atomx Control Panel. The Atomx Control Panel is static HTML and uses the Atomx API endpoint for everything.

(first path segment is always the api version e.g. /v3/)

HTTP GET to read from the API:

  1. /{Model}
  2. /{Model}/{ID}
  3. /{Model}/{ID}/{Attribute}

HTTP POST to create a new entry:

  1. /{Model}

HTTP PUT to update entries:

  1. /{Model}/{ID}
  2. /{Model}/{ID}/{Attribute}
  3. For PUT you could also use /{Model} and apply a filter that only returns a single entry
e.g. PUT to `/domains?hostname=mininova.org`

API Models

For a list of models and their attributes see: api models.

Special Endpoints

  • /login GET or POST request with id or email and password for login. Returns auth_token that must be added as an Authorization header for requests to non read-only models
  • /networks_list, /publishers_list, advertisers_list, sites_list, placements_list returns list of IDs and names for all available networks/publishers/advertisers
  • /search with a q url parameter that returns a list of ids and names of matching models for that search query. E.g. Search for everything containing mini: HTTP GET to /v3/search?q=*mini*
  • /report see: reporting
  • /websocket websocket endpoint. See websockets_beta
  • /{Model}/{ID}/history returns all changes of a resource.
  • /reset_password GET /reset_password?email=user@email.com to send password reset instructions per email to the user. POST /reset_password with json content { "hash": "longResetHashFromEmail", "password": "new_password" } to reset the user password.
    Note: to reset a password of a logged in user that remembers his password. POST (with a valid auth_token of the user) to /user/123 with 'old_password' and 'password' in the json.

URL Parameters

  • limit: number of entries to return. (default: 100; maximum limit is 1000)
  • offset: number of entries to skip. (default: 0)
  • sort: attribute to sort by in descending order. You can optionally specify the sort order by appending .asc or .desc to the attribute (default: id.asc). You can also sort by sub-attributes, e.g. GET /v3/creatives?sort=category.name.asc or by quickstats, e.g. GET /v3/campaigns?quickstats&sort=quickstats.lifetime.clicks.asc. If you specify a relationship model without specifying an attribute of it you sort by count. E.g. GET /v3/publishers?sort=sites.desc&limit=5 returns the 5 publishers that have the most sites.
  • depth: Specifies how attributes that are relationships to another model or a list of other models is returned. There are 3 options:
    • depth=0: don't return any relationship attributes at all
    • depth=1: return a list of attribute IDs (default)
    • depth=2: return the expanded attribute objects
  • attributes: comma separated list of attributes you want to have included in your result. You can also exclude certain attributes bei prepending '!' to the attribute name. (not set as defaults and all attributes are returned) e.g. get sites but only return id and names without anything else: HTTP GET to /v3/sites?attributes=id,name or get advertiser with id 3 but without campaigns and creatives attribute: /v3/advertiser/3?attributes=!creatives,!campaigns
  • expand: comma separated list of attributes to expand (instead of only showing the ID(s)). Useful if you don't want to set depth to a higher value because you only want one or a few attributes expanded or you set depth to 2 already and want to expand one attribute a level deeper. (not set as default) E.g. get all sites and also expand the domains /v3/sites?expand=domain
  • quickstats: If there is a quickstats URL parameter present the returned models will also include some stats for the model. E.g. return all publishers with stats HTTP GET /v3/publishers?quickstats or return advertiser/3 with stats: /v3/advertiser/3?quickstats quickstats can also accessed as an attribute of the model directly. E.g. return ONLY the stats of site/3: /v3/site/3/quickstats
  • attribute filter: every attribute other then the above (limit, offset, sort, depth, attributes, expand) is used as a filter for the result set. The URL parameter in general looks like attribute_to_filter=filter_string If attribute_to_filter is starting with ! the filter is negated. filter_string can be a comma separated list of multiple values or contain * as wildcard for matches in strings. (no filter set as default) E.g. find all .mx TLDs /v3/domains?hostname=*.mx

Usage with curl

To login and receive the authentication token:

$ curl -X POST -d '{"email": "test@example.com", "password": "test"}' -H "Content-Type: application/json" api.atomx.com/v3/login

A sample response would be:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Tue, 28 Oct 2014 11:37:25 GMT

{
    "auth_token": "eyJhbGciOiXW4UzUxMiIsInR5cCI6IkpXVCJ9.eyJpYXQiWeE0NTkyMjk4MTcsImV4cCI6MTQ1OTgzNDYxNywic3ViIjo0fQ.Dzp7IG3Lp9KcK881mZpp9ge2FKbQ0DlU-eqDsAl8OsE0awlMivL5CDIiETZc9qvRIFxmUXdnasXWLLabl02iig",
    "message": "test (user id 1) logged in",
    "success": true,
    "user": {
        "created_at": "2014-09-09T15:34:56",
        "email": "test@example.com",
        "id": 1,
        "name": "test",
        "state": "ACTIVE",
        "updated_at": "2014-10-14T19:01:11"
    }
}

With the auth token you can access all other models where the user has read or write access. To do so add an 'Authorization' Header with 'Bearer ' + auth_token as value.

E.g. get all sites:

$ curl -H 'Authorization: Bearer eyJhbGciOiXW4UzUxMiIsInR5cCI6IkpXVCJ9.eyJpYXQiWeE0NTkyMjk4MTcsImV4cCI6MTQ1OTgzNDYxNywic3ViIjo0fQ.Dzp7IG3Lp9KcK881mZpp9ge2FKbQ0DlU-eqDsAl8OsE0awlMivL5CDIiETZc9qvRIFxmUXdnasXWLLabl02iig' api.atomx.com/v3/sites

Would result in a json response like:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "filter": [],
    "limit": null,
    "offset": null,
    "sites": [
        {
            "advertisers": [],
            "advertisers_filter_action": "EXCLUDE",
            "created_at": "2014-10-29T17:36:42",
            "domain": 0,
            "domain_id": 0,
            "id": 5,
            "minimum_internal_bid": 0.0,
            "name": "Test site",
            "networks": [],
            "networks_filter_action": "EXCLUDE",
            "placements": [
                1
            ],
            "publisher": 2,
            "publisher_id": 2,
            "state": "ACTIVE",
            "updated_at": "2014-10-29T17:38:25"
        },
        {
            "advertisers": [],
            "advertisers_filter_action": "EXCLUDE",
            "created_at": "2014-10-29T17:54:21",
            "domain": 25040,
            "domain_id": 25040,
            "id": 6,
            "minimum_internal_bid": 0.0,
            "name": "Mininova.org",
            "networks": [],
            "networks_filter_action": "EXCLUDE",
            "placements": [
                2
            ],
            "publisher": 3,
            "publisher_id": 3,
            "state": "ACTIVE",
            "updated_at": "2015-01-27T22:00:00"
        },
        /* {...  more sites cut for documentation */ ...}
    ],
    "sort": "id.asc",
    "success": true,
    "timestamp": "2015-04-03T00:14:35.072516"
}

To create a new entry you have to POST with the necessary data you want to set. E.g. creating a new Site:

$ curl -H 'Authorization: Bearer eyJhbGciOiXW4UzUxMiIsInR5cCI6IkpXVCJ9.eyJpYXQiWeE0NTkyMjk4MTcsImV4cCI6MTQ1OTgzNDYxNywic3ViIjo0fQ.Dzp7IG3Lp9KcK881mZpp9ge2FKbQ0DlU-eqDsAl8OsE0awlMivL5CDIiETZc9qvRIFxmUXdnasXWLLabl02iig' -X POST -d '{"name": "test site", "publisher_id": "1"}' -H "Content-Type: application/json" 127.0.0.1:6543/v3/site

Would create a new Site and the response would look like:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "site": {
        "created_at": "2014-10-28T21:56:44",
        "creative_attributes_exclude": "",
        "domain_id": 0,
        "id": 15,
        "minimum_internal_bid": 0.0,
        "name": "test site",
        "publisher_id": "1",
        "state": "INACTIVE"
    },
    "status": "OK"
}

Websockets (Beta)

Warning: Atomx API websocket implementation is still in beta and the protocol may change in the future.

The api has a websocket endpoint under wss://api.atomx.com/v3/websocket?auth_token=YOUR_USER_AUTH_TOKEN_HERE.

Once connected you can subscribe to different 'channels' that you're interested in and want to receive real-time updates from. By default you're always subscribed to the 'system' channel that gives you general information and also sends you message if your subscription request was successful or not.

So far (this may change in the future), there are 2 different channels for each model. One for “normal” updates like a name or state change etc and one for a live quickstats that sends you a new 'lifetime' spent value (only advertiser and campaigns).

You can subscribe to a channel by sending {"action":"subscribe","model":"advertiser:12345"} for “regular” updates and/or {"action":"subscribe","model":"stats:advertiser:12345"} for quickstats.

When you don't want updates anymore you can unsubscribe the same way you subscribed. E.g.: {"action":"unsubscribe","model":"advertiser:12345"}, and/or {"action":"unsubscribe","model":"stats:advertiser:12345"}.