**This is an old revision of the document!**

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.


Invoice lists and the invoice PDFs can be received with the different /invoices endpoints.

Invoice type is one of: advertiser, publisher, network-sell or network-buy.

Adding a 'date>' request parameter changes the start date (inclusive) of the invoice list and 'date<' the end date (exclusive). date has the format YYYY-MM.

E.g. GET :api/invoices/network-buy/42?date>=2016-10&date<=2017-03 will get all invoices from 10.2016 (including) to 03.2017 (excluded).

  • /invoices/{type} Receive all invoices for the specified type. If no data parameter is given it will return a list of invoices for the current month.
  • /invoices/{type}/{id} Receive all invoice for the specified type plus id. If no date parameter is given it will default to January this year to the current month.

    E.g. to receive all invoices for advertiser with id 42 of the current year GET /invoices/advertiser/42

  • /invoices/{type}/{id}/{date} Download the invoice PDF for the specified date.

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