API v1

1. Overview

This documentation describes NewReleases API v1 resources.

2. Root endpoint

NewReleases can be used as a web service available on newreleases.io address and some of functionalities are available over JSON API on api.newreleases.io domain.

To use publicly available service, the endpoint is:

https://api.newreleases.io/v1

3. API Version

All API paths are prefixed with a version number, as part of the root endpoint.

This document describes only v1 version of the API, which is the first stable version.

4. Authentication

Each HTTP request requires X-Key header to be provided with an API key as a value, or as username or password in Basic Auth header. All GET requests in this API can be performed in browser by passing API key in either username or password field in browser authentication dialog.

API key is unique for every NewReleases user account and can be generated on a website under API keys Settings page. Every user account can have multiple keys. It is also filtered by IP subnets that user can specify on the same page.

If the token is missing or invalid, API will return an Unauthorized response.

Examples:

curl -H "X-Key: ewcppcsk781h1bwlxp0q3pe8gf7322dl8n52" \
    https://api.newreleases.io/v1/projects

curl -u ewcppcsk781h1bwxp0q3pe8gf7322d8n52: \
    https://api.newreleases.io/v1/projects

4.1. Auth Keys

Auth endpoint /v1/auth/keys additionally accepts Basic Auth header with user’s login credentials: email address and password.

5. Rate Limiting

Rate limiting is applied on every API request, in a way that GET requests reduce the number of available requests per hour by 1 and all other requests by the value of 10.

Additional HTTP response headers are returned with more information:

X-Ratelimit-Limit: The maximum number of requests that the user is permitted to make per hour.
X-Ratelimit-Remaining: The number of requests remaining in the current rate limit window.
X-Ratelimit-Reset: Seconds remaining until current rate limit window reset to the maximal value.
Retry-After: Seconds remaining until new requests are permitted when limit is reached.

If X-Ratelimit-Limit header is absent, no limit is enforced.

When rate limit is reached, a Too Many Requests response will be returned.

6. Queries

NewReleases API uses HTTP for communication and this section describes HTTP requests, their parameters and responses from the API. Beside specified error responses for each query, the Internal Server Error may occur.

If resource URL path is not valid, a Not Found response will be returned.

In case that the request body can not be decoded from JSON, a Bad Request response will be returned. All POST requests must have Content-Type: application/json header.

URL paths may contain parameters which are indicated with a variable name surrounded with curly brackets {}.

6.1. List Projects

GET /v1/projects

Query parameters:

page: (integer, default: 1)
order: (string, default: “updated”, possible values: “name”, “updated”, “added”)
reverse: (no value, provided reverses ordering)
tag: (string, tag ID to filter projects)

Response returns resource:

projects: (array of Project)
total_pages: (integer)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/projects

{
  "projects": [
    {
      "id": "pf4w494lbjsd3ydp5hnf4gsptw",
      "name": "golang/go",
      "provider": "github",
      "url": "https://github.com/golang/go/releases",
      "email_notification": "hourly",
      "exclude_updated": true
    }
  ],
  "total_pages": 1
}

6.2. List Projects By Provider

GET /v1/projects/{provider}

Query parameters:

page: (integer, default: 1)
order: (string, default: “updated”, possible values: “name”, “updated”, “added”)
reverse: (no value, provided reverses ordering)

If q parameter is provided for search, other parameters are ignored.

Response returns resource:

projects: (array of Project)
total_pages: (integer)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/projects/github

{
  "projects": [
    {
      "id": "pf4w494lbjsd3ydp5hnf4gsptw",
      "name": "golang/go",
      "provider": "github",
      "url": "https://github.com/golang/go/releases",
      "email_notification": "hourly",
      "exclude_updated": true
    }
  ],
  "total_pages": 1
}

6.3. Search Projects

GET /v1/projects/search

Query parameters:

q: (string, required)
provider: (string)

Response returns resource:

q: (string)
provider: (string, default: “”)
projects: (array of Project)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/projects/search?q=go

{
  "q": "go",
  "projects": [
    {
      "id": "pf4w494lbjsd3ydp5hnf4gsptw",
      "name": "golang/go",
      "provider": "github",
      "url": "https://github.com/golang/go/releases",
      "email_notification": "hourly",
      "exclude_updated": true
    }
  ]
}

6.4. Get Project

GET /v1/projects/{id}

URL parameters:

id: (string)

GET /v1/projects/{provider}/{projectName}

URL parameters:

provider: (string)
projectName: (string)

Returns Project resource.

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/pf4w494lbjsd3ydp5hnf4gsptw

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/golang/go

{
    "id": "pf4w494lbjsd3ydp5hnf4gsptw",
    "name": "golang/go",
    "provider": "github",
    "url": "https://github.com/golang/go/releases",
    "email_notification": "hourly",
    "exclude_updated": true
}

6.5. Add Project

POST /v1/projects

Request body properties:

provider: (string, required)
name: (string, required)
email_notification: (string, default: “none”, possible values: “none”, “instant”, “hourly”, “daily”, “weekly”, “default”)
slack_channels: (array of strings, default: [])
telegram_chats: (array of strings, default: [])
discord_channels: (array of strings, default: [])
hangouts_chat_webhooks: (array of strings, default: [])
microsoft_teams_webhooks: (array of strings, default: [])
mattermost_webhooks: (array of strings, default: [])
rocketchat_webhooks: (array of strings, default: [])
matrix_rooms: (array of strings, default: [])
webhooks: (array of strings, default: [])
exclude_version_regexp: (array of Exclusion, default: [])
exclude_prereleases: (boolean, default: false)
exclude_updated: (boolean, default: false)
note: (string, default: “”)
tags: (array of strings, default: [], possible values tag IDs)

Response returns Project resource.

curl -H "X-Key: API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"provider":"github", "name": "golang/go"}' \
     https://api.newreleases.io/v1/projects

{
    "id": "pf4w494lbjsd3ydp5hnf4gsptw",
    "name": "golang/go",
    "provider": "github",
    "url": "https://github.com/golang/go/releases",
    "email_notification": "daily"
}

6.6. Update Project

POST /v1/projects/{id}

URL parameters:

id: (string)

POST /v1/projects/{provider}/{projectName}

URL parameters:

provider: (string)
projectName: (string)

Request body properties:

email_notification: (string, default: [no change], possible values: “none”, “instant”, “hourly”, “daily”, “weekly”, “default”)
slack_channels: (array of strings, default: [no change])
telegram_chats: (array of strings, default: [no change])
discord_channels: (array of strings, default: [no change])
hangouts_chat_webhooks: (array of strings, default: [no change])
microsoft_teams_webhooks: (array of strings, default: [no change])
mattermost_webhooks: (array of strings, default: [no change])
rocketchat_webhooks: (array of strings, default: [no change])
matrix_rooms: (array of strings, default: [no change])
webhooks: (array of strings, default: [no change])
exclude_version_regexp: (array of Exclusion, default: [no change])
exclude_prereleases: (boolean, default: [no change])
exclude_updated: (boolean, default: [no change])
note: (string, default: “”)
tags: (array of strings, default: [], possible values tag IDs)

Response returns Project resource.

curl -H "X-Key: API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"exclude_updated": true}' \
     https://api.newreleases.io/v1/projects/pf4w494lbjsd3ydp5hnf4gsptw

curl -H "X-Key: API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"exclude_updated": true}' \
     https://api.newreleases.io/v1/projects/github/golang/go

{
    "id": "pf4w494lbjsd3ydp5hnf4gsptw",
    "name": "golang/go",
    "provider": "github",
    "url": "https://github.com/golang/go/releases",
    "email_notification": "daily",
    "exclude_updated": true
}

6.7. Delete Project

DELETE /v1/projects/{id}

URL parameters:

id: (string)

DELETE /v1/projects/{provider}/{projectName}

URL parameters:

provider: (string)
projectName: (string)

Response returns OK.

curl -H "X-Key: API_KEY" \
     -X DELETE \
     https://api.newreleases.io/v1/projects/pf4w494lbjsd3ydp5hnf4gsptw

curl -H "X-Key: API_KEY" \
     -X DELETE \
     https://api.newreleases.io/v1/projects/github/golang/go

{
    "message": "OK",
    "code": 200
}

6.8. List Project Releases

Query parameters:

page: (integer, default: 1)

GET /v1/projects/{id}/releases

URL parameters:

id: (string)

GET /v1/projects/{provider}/{projectName}/releases

URL parameters:

provider: (string)
projectName: (string)

Response returns resource:

releases: (array of Release)
total_pages: (integer)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/projects/8wdvh4w9bhsvzclz4ynaqpcpvg/releases

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/projects/github/nodejs/node/releases

{
  "releases": [
    {
      "version": "v11.12.0",
      "date": "2019-03-15T21:16:54Z",
      "has_note": true
    },
    {
      "version": "v11.11.0",
      "date": "2019-03-06T19:44:17Z",
      "has_note": true
    },
    {
      "version": "v10.15.3",
      "date": "2019-03-05T17:37:13Z",
      "has_note": true
    },
    {
      "version": "v6.17.0",
      "date": "2019-02-28T11:23:55Z"
    },
    {
      "version": "v8.15.1",
      "date": "2019-02-28T11:20:35Z"
    },
    {
      "version": "v10.15.2",
      "date": "2019-02-28T11:17:15Z"
    },
    {
      "version": "v11.10.1",
      "date": "2019-02-28T11:03:34Z"
    },
    {
      "version": "v11.10.0",
      "date": "2019-02-14T23:03:07Z",
      "has_note": true
    },
    {
      "version": "v11.9.0",
      "date": "2019-01-30T22:13:59Z",
      "has_note": true
    },
    {
      "version": "v11.8.0",
      "date": "2019-01-29T20:38:32Z",
      "has_note": true
    }
  ],
  "total_pages": 54
}

6.9. Get Project Release

GET /v1/projects/{id}/releases/{version}

URL parameters:

id: (string)
version: (string)

GET /v1/projects/{provider}/{projectName}/releases/{version}

URL parameters:

provider: (string)
projectName: (string)
version: (string)

Returns Release resource.

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/8wdvh4w9bhsvzclz4ynaqpcpvg/releases/v11.12.0

{
  "version": "v11.12.0",
  "date": "2019-03-15T21:16:54Z",
  "has_note": true
}

6.10. Get Latest Non-Excluded Release

GET /v1/projects/{id}/latest-release

URL parameters:

id: (string)

GET /v1/projects/{provider}/{projectName}/latest-release

URL parameters:

provider: (string)
projectName: (string)

Returns Release resource.

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/8wdvh4w9bhsvzclz4ynaqpcpvg/latest-release

{
  "version": "v11.12.0",
  "date": "2019-03-15T21:16:54Z",
  "has_note": true
}

6.11. Get Project Release Note

GET /v1/projects/{id}/releases/{version}/note

URL parameters:

id: (string)
version: (string)

GET /v1/projects/{provider}/{projectName}/releases/{version}/note

URL parameters:

provider: (string)
projectName: (string)
version: (string)

Returns Release Note resource.

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/8wdvh4w9bhsvzclz4ynaqpcpvg/releases/v11.12.0/note

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/project/github/nodejs/node/releases/v11.12.0/note

{
  "title": "2019-03-15, Version 11.12.0 (Current), @BridgeAR",
  "message": "<h3>Notable Changes</h3>\n\n<ul>\n<li>...",
  "url": "https://github.com/nodejs/node/releases/tag/v11.12.0"
}

6.12. Get Providers

GET /v1/providers

Query parameters:

added: (no value, provided returns only added providers)

Response returns resource:

providers: (array of strings)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/providers

{
  "providers": [
    "artifacthub",
    "bitbucket",
    "cargo",
    "codeberg",
    "cpan",
    "debian-gitlab",
    "dockerhub",
    "ecr-public",
    "exozyme",
    "freedesktop-gitlab",
    "gcr",
    "gems",
    "ghcr",
    "gitea",
    "github-npm",
    "github",
    "gitlab",
    "gnome-gitlab",
    "gnu-savannah",
    "hex",
    "kde-gitlab",
    "maven",
    "npm",
    "packagist",
    "pypi",
    "quay",
    "sourceforge",
    "xfce-gitlab",
    "yarn"
  ]
}

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/providers?added

{
  "providers": [
    "github",
    "pypi"
  ]
}

6.13. Get Slack Channels

GET /v1/slack-channels

Response returns resource:

channels: (array of Slack Channel)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/slack-channels

{
  "channels": [
    {
      "id": "00q3pe8gf7322d8n52bgrl551",
      "channel": "releases",
      "team_name": "My Slack Team"
    }
  ]
}

6.14. Get Telegram Chats

GET /v1/telegram-chats

Response returns resource:

channels: (array of Telegram Chat)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/telegram-chats

{
  "channels": [
    {
      "id": "51732818n52bgh1bwlpf2drl5",
      "type": "group",
      "name": "My Telegram Chat"
    }
  ]
}

6.15. Get Discord Channels

GET /v1/discord-channels

Response returns resource:

channels: (array of Discord Channel)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/discord-channels

{
  "channels": [
    {
      "id": "08n52bgrl550q3pe8gf7322d1",
      "name": "My Discord"
    }
  ]
}

6.16. Get Hangout Chat Webhooks

GET /v1/hangouts-chat-webhooks

Response returns resource:

webhooks: (array of Webhook)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/hangouts-chat-webhooks

{
  "webhooks": [
    {
      "id": "ewcppcsk781h1bwlp0q3pe8gf7",
      "name": "My Hangouts"
    }
  ]
}

6.17. Get Microsoft Teams Webhooks

GET /v1/microsoft-teams-webhooks

Response returns resource:

webhooks: (array of Webhook)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/microsoft-teams-webhooks

{
  "webhooks": [
    {
      "id": "w1a56q4es0dvtl84tdst4ezma8",
      "name": "My Team"
    }
  ]
}

6.18. Get Mattermost Webhooks

GET /v1/mattermost-webhooks

Response returns resource:

webhooks: (array of Webhook)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/mattermost-webhooks

{
  "webhooks": [
    {
      "id": "4t0dvtl8dst4ezma8w1a56q4es",
      "name": "My Channel"
    }
  ]
}

6.19. Get Rocket.Chat Webhooks

GET /v1/rocketchat-webhooks

Response returns resource:

webhooks: (array of Webhook)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/rocketchat-webhooks

{
  "webhooks": [
    {
      "id": "0dzm56q4a8wvtesl8dst4e1a4t",
      "name": "My Chat"
    }
  ]
}

6.20. Get Matrix Rooms

GET /v1/matrix-rooms

Response returns resource:

rooms: (array of Matrix Room)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/matrix-rooms

{
  "webhooks": [
    {
      "id": "56q4zma8w4dvtle4t08dstes1a",
      "name": "My Room",
      "homeserver_url": "https://matrix-client.matrix.org",
      "internal_room_id": "!CklwygGihbIcsulFYK:matrix.org"
    }
  ]
}

6.21. Get Webhooks

GET /v1/webhooks

Response returns resource:

webhooks: (array of Webhook)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/webhooks

{
  "webhooks": [
    {
      "id": "aw680q7n6vv2s75snp2lpr006m",
      "name": "My Webhook"
    }
  ]
}

6.22. Get Tags

GET /v1/tags

Response returns resource:

tags: (array of Tag)

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/tags

{
  "tags": [
    {
      "id": "cf35e5b69d74",
      "name": "Go"
    },
    {
      "id": "d74f35ce69b5",
      "name": "Python"
    }
  ]
}

6.23. Add Tag

POST /v1/tags

Request body properties:

name: (string, required)

Response returns Tag.

curl -H "X-Key: API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "Go"}' \
     https://api.newreleases.io/v1/tags

{
  "id": "cf35e5b69d74",
  "name": "Go"
}

6.24. Get Tag

GET /v1/tags/{id}

URL parameters:

id: (string)

Response returns Tag.

curl -H "X-Key: API_KEY" \
     https://api.newreleases.io/v1/tags/cf35e5b69d74

{
  "id": "cf35e5b69d74",
  "name": "Go"
}

6.25. Update Tag

POST /v1/tags/{id}

URL parameters:

id: (string)

Request body properties:

name: (string, required)

Response returns Tag.

curl -H "X-Key: API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "Golang"}' \
     https://api.newreleases.io/v1/tags/cf35e5b69d74

{
  "id": "cf35e5b69d74",
  "name": "Golang"
}

6.26. Delete Tag

DELETE /v1/tags/{id}

URL parameters:

id: (string)

Response returns OK.

6.27. Get Auth Keys

GET /v1/auth/keys

Response returns resource:

keys: (array of Auth Key)

Only Basic Auth headers with user’s login credentials (email address and password) are accepted for authentication.

curl -u "you@example.com:password" \
     https://api.newreleases.io/v1/auth/keys

{
  "keys": [
    {
      "name": "My Key",
      "secret": "ewcppcsk781h1bwxplq3pe8gf7322d8n52bg",
      "authorized_networks": [
        "::/0",
        "0.0.0.0/0"
      ]
    }
  ]
}

7. Resources

Request and response HTTP bodies are JSON-encoded as JSON objects. In this section, resources that represent data that NewRelease is managing are described as properties of JSON objects with their types and default values where properties may be omitted in the response.

7.1. Project

Properties:

id: (string)
name: (string)
provider: (string)
url: (string)
email_notification: (string, default: “none”, possible values: “none”, “instant”, “hourly”, “daily”, “weekly”, “default”)
slack_channels: (array of strings, default: [])
telegram_chats: (array of strings, default: [])
discord_channels: (array of strings, default: [])
hangouts_chat_webhooks: (array of strings, default: [])
microsoft_teams_webhooks: (array of strings, default: [])
mattermost_webhooks: (array of strings, default: [])
rocketchat_webhooks: (array of strings, default: [])
webhooks: (array of strings, default: [])
exclude_version_regexp: (array of Exclusion, default: [])
exclude_prereleases: (boolean, default: false)
exclude_updated: (boolean, default: false)
note: (string, default: “”)
tags: (array of strings, default: [], possible values tag IDs)

Available providers are:

github
gitlab
codeberg
gitea
bitbucket
gnu-savannah
exozyme
pypi
maven
npm
yarn
gems
packagist
nuget
cargo
hex
cpan
dockerhub
ecr-public
gcr
quay
artifacthub
sourceforge
debian-gitlab
freedesktop-gitlab
gnome-gitlab
kde-gitlab
xfce-gitlab

7.2. Exclusion

Properties:

value: (string)
inverse: (boolean, default: false)

7.3. Release

Properties:

version: (string)
date: (string)
cve: (array of string, default: [])
is_prerelease: (boolean, default: false)
is_updated: (boolean, default: false)
is_excluded: (boolean, default: false)
has_note: (boolean, default: false)

7.4. Release Note

Properties:

title: (string: default: “”)
message: (string: default: “”)
url: (string: default: “”)

7.5. Slack Channel

Properties:

id: (string)
channel: (string)
team_name: (string)

7.6. Telegram Chat

Properties:

id: (string)
type: (string: possible values: “provate”, “group”, “supergroup”, “channel,)
name: (string)

7.7. Discord Channel

Properties:

id: (string)
name: (string)

7.8. Webhook

Properties:

id: (string)
name: (string)

7.9. Matrix Room

Properties:

id: (string)
name: (string)
homeserver_url: (string)
internal_room_id: (string)

7.10. Tag

Properties:

id: (string)
name: (string)

7.11. Auth Key

Properties:

name: (string)
secret: (string)
authorized_networks (array of string)

8. API Status Codes

API utilizes HTTP Status codes as well as specific codes for more granular error reporting.

Message responses have the following example of JSON-encoded body:

{
  "message": "OK",
  "code": 200
}

Bad Request response contains additional field describing specific errors:

{
  "message": "Bad Request",
  "code": 400,
  "errors": [
    "Project name is required."
  ]
}

Code	HTTP Status	Message
200	OK	OK
400	Bad Request	Bad Request
401	Unauthorized	Unauthorized
403	Forbidden	Forbidden
404	Not Found	Not Found
405	Method Not Allowed	Method Not Allowed
429	Too Many Requests	Too Many Requests
500	Internal Server Error	Internal Server Error
503	Service Unavailable	Maintenance

NewReleases Slack Telegram Discord Hangouts Chat Microsoft Teams Mattermost Rocket.Chat Matrix Webhooks API Organizations Badge