Global IRT (Incident Response Team) is a project to describe common IRT and abuse contact information. Global IRT participant directories are encouraged to provide a RESTful API that can provide basic querying capabilities to the repository, and return information following Global IRT specification.
Each directory is encouraged to be conformant to this specification and register the compatible API endpoint with the the Global IRT initiative for sourcename reservation and public listing of the API for the CERT community.
|Repository (sourcename)||Endpoint URL||Status|
Each repository will be treated in this document as the application responsible for the API. There are some rules that are requirements for these applications: these rules will be informed that the application MUST comply. The optional alternatives will be written like what the application SHOULD do, but by not doing doesn't mean that the application is not conformant to this documentation.
The URLs listed in this document are prefixed by the HTTP method required to use them, followed by the address relative to the Endpoint URL of each repository. Take for example the teams listing, which uses the address
GET /teams. It must be read as a
GET request to the
[Endpoint URL]/teams — to query FIRST.Org repository, you could use
curl -X GET https://api.first.org/global-irt/v1/teams.
The default output format is
application/json. The applications are encouraged to support additional formats but it's not a requirement. The accepted format should be requested either as a
Accept: header or as an extension to the requested URL. These are suggestions for additional formats to be supported:
|application/json||.json (default)||JSON. Should be pretty-printed by default. This will be the format used if no extension or
|application/yaml||.yml||YAML, a more human-readable format. Applications should use two spaces as indentation and maximum column width of 80 characters.|
|application/xml||.xml||XML. Should be pretty-printed by default. Should not contain namespaces and different encodings.|
|application/csv||.csv||Comma-separated values. The first line contains the column names.|
The applications must use UTF8 as the request/response encoding. Applications are also encouraged to compress output with Gzip if the request header
Accept-Encoding: compress, gzip is present.
Parameters can be set at the query string of the request. Parameters must be keypair values assigned with an
= (equal sign):
key=value. The values must be URL encoded (RFC 3986), and multiple parameters must be separated by
& (ampersand sign).
There are some parameters that are reserved for pagination and output control. These parameters are eligible for several methods and should not be used for a application-specific purpose.
|fields||string||Comma-separated list of fieldnames to be retrieved. Used only for limiting the available resultset.|
|limit||integer||Limits the maximun number of records to be shown. Should be a number between 1 and 100.|
|offset||integer||Offsets the list of records by this number. The first item is 0.|
|sort||string||Comma-separated list of fieldnames to be used to sort the resultset. Fields starting with "-" (minus sign) indicate a descending order. Each application should define its default sorting options.|
|callback||string||Only for JSONP resultsets, adds the
GET request will return a proper response object, either using the HTTP response header (if the parameter
envelope was not set to
false) or at the response body. For example, the request for one brazilian CERT listing only team name and e-mail at FIRST.Org repository:
Last-Modified will refer to the last time the resultset that corresponds to this URL was modified, this information can be used for caching (browsers would request the
If-Modified-Since header to check if it was modified).
X-Version points out the actual API version used.
X-Total-Count header indicates how many fields were matched for this request. Using the parameters
limit is possible to paginate the results properly.
This information, when queried with
envelope=true will be present at the response body, and the resultset will be available at the
Note: using a
limit of "0" (zero) will still return a valid response object with the proper count of matches.
Retrieves or queries the Teams public listing. Applications should enable filtering of these lists.
Each response object may contain the following description fieldnames. Empty values are omitted from the resultset. Every property might be used to query/fiter the list.
|short-team-name||string||Short Team name. This should be preferreably under 50 characters.|
|official-team-name||string||Official Team name.|
|postal-address||string||Valid contact postal address.|
|country-code||string||Official country of the team. Uses ISO 3166-1 alpha-2 codes.|
|additional-country-code||list||Other countries the team supports. Uses ISO 3166-1 alpha-2 codes.|
|website||list||List of valid websites, news and social media URLs.|
|string||Official contact e-mail.|
|host||string||Host organization of the team.|
|establishment||date||Team date of establishment. Uses ISO 8601 format.|
|phone-numbers||list||List of valid phone and fax numbers for contacting the team.|
|enckeys||list||List of valid PGP key ids that can be used for encrypting content to the team.|
|operating-hours||string||Textual description of operating hours of the team.|
|constituency||string||Official team constituency. Should use a controlled vocabulary.|
|constituency-code||string||Repository-specific code for representing the constituency.|
|constituency-description||string||Free textual constituency description.|
|source-name||string||Name of the repository.|
|last-modified||string||Date the entity was last updated or verified.|
Properties that are specific to one repository should be prefixed with
-[repository code]. For example, FIRST.Org repository might make available the
member-type property as
|-first-member-type||string||FIRST.Org membership type. Should be either Full Member or Liaison.|
All output fields, with the exception of last-modified, can be used as params for queries. They are used as exact terms (case insensitive) compared to the field value. In addition, these following parameters permit the querying in several fields at once:
|team||string||Free text search on both
|country||string||Accepts a comma-separated list of country codes to filter the resultset of both
|region||string||Region to search the teams for. Uses ISO 3166 region names.|
|q||string||Searches for the words in all available fields (except
Example response object
Last modified: June 12th, 2016 version: 1.0.1-beta