Endpoints, API v3

These endpoints are under development and should not be considered stable. Only endpoints with changes from v2 are listed here.

Authorization

Use the endpoints in version 2.

Incident endpoints

See v2 for the other endpoints.

• /api/v3/incidents/:

  • GET: returns all incidents - both open and historic

    Query parameters: All query parameters are optional. If a query parameter is not included or empty, for instance acked=, then the rows returned are not affected by that filter and shows rows of all kinds of that value, for instance both “acked” and “unacked” in the case of acked=.

    Filtering parameters:

    acked=true|false

    Fetch only acked (true) or unacked (false) incidents.

    duration__gte=number

    Fetch only incidents that are or have been open for equal to or more than (number) minutes.

    end_time__gte=end-time

    Fetch only incidents that ended on or later than (end-time).

    end_time__isnull=true|false

    Fetch only stateless (true) or stateful (false) incidents.

    end_time__lte=end-time

    Fetch only incidents that ended on or earlier than (end-time).

    level__lte=1|2|3|4|5

    Fetch only incidents that have a level less or equal than (level).

    open=true|false

    Fetch only open (true) or closed (false) incidents.

    stateful=true|false

    Fetch only stateful (true) or stateless (false) incidents.

    source__id__in=ID1[,ID2,..]

    Fetch only incidents with a source with numeric id ID1 or ID2 or..

    source__name__in=NAME1[,NAME2,..]

    Fetch only incidents with a source with name NAME1 or NAME2 or..

    source__type__in=NAME1[,NAME2,..]

    Fetch only incidents with a source of a type with numeric id ID1 or ID2 or..

    source_incident_id=ID

    Fetch only incidents with source_incident_id set to ID.

    start_time__gte=start-time

    Fetch only incidents that started on or later than (start-time).

    start_time__lte=start-time

    Fetch only incidents that started on or earlier than (start-time).

    stateful=true|false

    Fetch only stateful (true) or stateless (false) incidents.

    ticket=true|false

    Fetch only incidents with a ticket url (true) or without (false).

    tags=key1=value1,key1=value2,key2=value

    Fetch only incidents with one or more of the tags. Tag-format is “key=value”. If there are multiple tags with the same key, only one of the tags needs to match. If there are multiple keys, one of each key must match.

    So:

    URL reformatted for readability

      /api/v3/incidents/?acked=false\
                      &open=true\
                      &stateful=true\
                      &source__id__in=1\
                      &tags=\
                        location=broomcloset,\
                        location=understairs,\
                        problem=onfire
    

    will fetch incidents that are all of “open”, “unacked”, “stateful”, from source number 1, with “location” either being “broomcloset” or “understairs”, and that is on fire.

    Note

    If the boolean parameters are not given a value or are left out, that is interpreted as not filtering at all on that parameter, showing both true and false entries.

    Paginating parameters:

    cursor=LONG RANDOM STRING|null

    Go to the page of that cursor. The cursor string for next and previous page is part of the response body.

    page_size=INTEGER

    The number of rows to return. Default is 100.

    So: api/v3/incidents/?cursor=cD0yMDIw&page_size=10 will go to the page indicated by cD0yMDIw and show the next 10 rows from that point onward. Do not attempt to guess the cursor string. null means there is no more to fetch.

    Example response body

      {
          "next": "http://localhost:8000/api/v3/incidents/?cursor=cD0yMDIwLTA5LTIzKzEzJTNBMDIlM0ExNi40NTU4MzIlMkIwMCUzQTAw&page_size=10",
          "previous": null,
          "results": [
              {
                  "pk": 10101,
                  "start_time": "2011-11-11T11:11:11+02:00",
                  "end_time": "2011-11-11T11:11:12+02:00",
                  "source": {
                      "pk": 11,
                      "name": "Uninett GW 3",
                      "type": {
                          "name": "nav"
                      },
                      "user": 12,
                      "base_url": "https://somenav.somewhere.com",
                      "last_seen": "2011-11-11T11:11:12+02:00"
                  },
                  "source_incident_id": "12345",
                  "details_url": "https://uninett.no/api/alerts/12345/",
                  "description": "Netbox 11 <12345> down.",
                  "ticket_url": "https://tickettracker.com/tickets/987654/",
                  "tags": [
                      "object=Netbox 4",
                      "problem_type=boxDown",
                      "color=red"
                  ],
                  "stateful": true,
                  "open": false,
                  "acked": false
              }
          ]
      }
    

    Pagination-support:

    next

    The link to the next page, according to the cursor, or null if on the last page.

    previous

    The link to the previous page, according to the cursor, or null if on the first page.

    results

    An array of the resulting subset of rows, or an empty array if there are no results.

    Refer to the section Explanation of terms for an explanation of the other fields.

  • POST: creates and returns an incident

    Example request body

      {
          "source": 11,
          "start_time": "2011-11-11 11:11:11.11111",
          "end_time": null,
          "source_incident_id": "12345",
          "details_url": "https://uninett.no/api/alerts/12345/",
          "description": "Netbox 11 <12345> down.",
          "ticket_url": "https://tickettracker.com/tickets/987654/",
          "tags": [
              "object=Netbox 4",
              "problem_type=boxDown"
          ]
      }
    

    Refer to the section Explanation of terms for an explanation of the fields.

• /api/v3/incidents/<int:pk>/:

  • GET: returns an incident by primary key

  • PATCH: modifies parts of an incident and returns it

    Example request body

      {
          "ticket_url": "https://tickettracker.com/tickets/987654/",
          "tags": [
              "object=Netbox 4",
              "problem_type=boxDown"
          ]
      }
    

    The fields allowed to be modified are:

    • details_url

    • ticket_url

    • tags

• /api/v3/incidents/<int:pk>/tags/:

  • GET: returns a list of all the tags for the incident given by the

  primary key

  • POST: adds one or more tags to the incident and returns the modified list

    Example request body

      [
          "object=Netbox 4",
          "problem_type=boxDown"
      ]
    

• /api/v3/incidents/<int:pk>/tags/<str:tag>/:

  • GET: returns a list of the tag specified be the incident primary key

  and the tag. Useful for checking if an incident has that specific tag.

  • DELETE: removes the given tag from the incident

• /api/v3/incidents/<int:pk>/ticket_url/:

  • PUT: modifies just the ticket url of an incident and returns it

    Example request body

      {
          "ticket_url": "https://tickettracker.com/tickets/987654/",
      }
    

    Only ticket_url may be modified.

• /api/v3/incidents/sources/:

  • GET: Returns a list of all sources

    Example response body

    [
      {
        "pk": 1,
        "name": "argus",
        "type": {
          "name": "argus"
          },
        "user": 1,
        "base_url": "",
        "last_seen": "2026-07-31T08:58:05.806388+02:00"
      }
    ]
    

• GET to /api/v3/incidents/mine/: behaves similar to /api/v3/incidents/, but will only show the incidents added by the logged in user, and no filtering on source or source type is possible.

Notification profile endpoints

See v2 for the other endpoints.

• /api/v3/notificationprofiles/destinations/:

  • GET: returns the logged in user’s destination-configs

    Example response body

      [
        {
          "pk": 2,
          "media": {
            "slug": "email",
            "name": "Email",
            "installed": true
          },
          "label": "work",
          "suggested_label": "Email: work@example.com",
          "settings": {
            "synced": false,
            "email_address": "work@example.com"
          }
        },
        {
          "pk": 3,
          "media": {
            "slug": "sms",
            "name": "SMS",
            "installed": true
          },
          "label": "work",
          "suggested_label": "SMS: +4747474747",
          "settings": {
            "phone_number": "+4747474747"
          }
        }
      ]
    

  • POST: creates and returns a destination-config, which is then connected to the logged in user

    Example request body for email

      {
          "media": "email",
          "label": "Work email",
          "settings": {
                "email_address":"work@email.com"
          }
      }
    

    Example request body for sms

      {
          "media": "sms",
          "label": "Work phone",
          "settings": {
                "phone_number":"+4747474747"
          }
      }
    

• /api/v3/notificationprofiles/destinations/<int:pk>/:

  • GET: returns one of the logged in user’s destination-configs by primary key

  • PUT: updates and returns one of the logged in user’s destination-configs by primary key

    • Example request body: same as POST to /api/v3/notificationprofiles/destinations/

  • DELETE: deletes one of the logged in user’s destination-configs by primary key

• /api/v3/notificationprofiles/destinations/<int:pk>/duplicate/:

  • GET: returns True if another user has a destination with the same medium and settings as the destination with the given primary key

• /api/v3/notificationprofiles/media/:

  • GET: returns media

    Example response body

      [
        {
          "slug": "email",
          "name": "Email",
          "installed": true
        },
        {
          "slug": "sms",
          "name": "SMS",
          "installed": true
        }
      ]
    

• /api/v3/notificationprofiles/media/<slug:slug>/:

  • GET: returns one of the media by it’s slug

• /api/v3/notificationprofiles/media/<slug:slug>/json_schema/:

  • GET: returns the json schema of the media by it’s slug

    Example response body

      {
        "json_schema": {
          "title": "Email Settings",
          "description": "Settings for a DestinationConfig using email.",
          "type": "object",
          "required": [
            "email_address"
          ],
          "properties": {
            "email_address": {
              "type": "string",
              "title": "Email address"
            }
          },
          "$id": "http://localhost:8000/json-schema/email"
        }
      }