Version: v1

Introduction

The OdinEye API is a set of HTTP endpoints that provide support for integrations with a Valheim game server. For example, the API can be used to query the current online players, track boss progression or understand the current in-game day and day cycles.
The API is organized around REST: it accepts and returns JSON-encoded requests/responses, uses standard HTTP response codes, authentication, and verbs. Each REST API endpoint is documented individually, and the endpoints are categorized by the resource that they primarily affect.

Base URL

All URLs referenced in the documentation have the following base:

http://localhost:3000

When making API calls, the base URL (including the port) should be changed accordingly, matching the domain that is being used for the game server and the port where OdinEye is running.

Authentication

note

Authentication has not been implemented at this time.

Upon implementation, the API will utilize API Keys as the default authentication method. Subsequently, this documentation will be revised to include the necessary instructions.

Requests

Making a API request involves combining the standard HTTP verbs (GET, POST, etc) with the URL to the API, the URI to a resource, along with one or more HTTP request headers.

curl -L -X GET 'http://localhost:3000/v1/players' \
-H 'Accept: application/json'

Responses

API requests return HTTP status codes. These requests may also return JSON response bodies that include information about the resource.

Successful requests

Commonly used HTTP codes:

Status code	Description
200 Ok	The request succeeded.
201 Created	The request succeeded, and a new resource was created as a result.
204 No content	There is no content to send for this request.

Failed requests

Commonly used HTTP codes:

Status code	Description
400 Bad request	The server cannot or will not process the request due to something that is perceived to be a client error.
401 Unauthorized	The client is not authenticated.
403 Forbidden	The client does not have access rights to the content.
404 Not found	The server cannot find the requested resource.
500 Internal server error	The server has encountered a situation it does not know how to handle.

note

Error handling has not been implemented at this time.

Upon implementation, the API will utilize Problem Details (RFC-9457) as the default format for error responses.
Example:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400
}

Versioning

The OdinEye API is versioned with a single number included in the URL of the API endpoint (v1). This number symbolizes the major version number.
Any breaking changes made to the API will lead to an increase in the API version and a subsequent release. Breaking changes are changes that can potentially break an integration.