API: V2

So you're interested in utilizing elmah.io for your own needs? You're in luck! We do support third party integration through this JSON API.

Unlike previous versions of our API, V2 is no longer limited to logging errors. elmah.io is still great to log and display errors, but you can log everything from verbose messages to fatal errors. Throughout this document we refer to the data you want to log, simply as messages.

Before digging into HTTP requests, you should check out Elmah.Io.Client NuGet package, which offers a .NET client for our API.

Create message

POST/api/v2/messages

Body should contain a message in JSON or XML format. On successful creation a HTTP status code with value 201 is returned, including a Location header to indicate where the created resource can be requested.

Request

Parameters

logid
required
GUID The id of the log you would like to add the new message to

Example

POSThttps://elmah.io/api/v2/messages?logid=5082a1ce-c234-4c2e-92d4-5c5bd5a72854

Body
{
    "title": "This is a test message"
}

Response

Codes

200 Not Created Message were not created.
201 Created Message were successfully created.
403 Forbidden Request limit reached and message were not created.
404 Not Found Log ID not found.

Example

201 (Created)
HTTP Header
Location: https://elmah.io/api/v2/messages?id=6707A1B0A79C8E85&logid=5082a1ce-c234-4c2e-92d4-5c5bd5a72854

Get message

GET/api/v2/messages

Returns a single message by it's id and logid. If the message is found, the request returns a status code 200.

Request

Parameters

logid
required
GUID The id of the log you would like to get the message from
id
required
string The id of the message you would like to get.

Example

GEThttps://elmah.io/api/v2/messages?id=6707A1B0A79C8E85&logid=5082a1ce-c234-4c2e-92d4-5c5bd5a72854


Response

Codes

200 OK Message found.
404 Not Found Message not found.

Example:

200

Body
{
    "title": "This is a test message"
}

Get messages

GET/api/v2/messages

Returns a list of message objects by their logid. This request pages results by the parameters pageIndex and pageSize. Weather or not messages are found, the request returns status code 200 as long as the logid is found.

Request

Parameters

logid
required
GUID The id of the log you would like to get the messages from
query
optional
string A full-text or Lucene query to limit the messages by.
from
optional
datetime A start date and time to search from (not included).
to
optional
datetime An end date and time to search to (not included).
pageindex
optional
number The page to start on or 0 if not set.
pagesize
optional
number The number of messages to load (max 100) or 15 if not set.

Example

GEThttps://elmah.io/api/v2/messages?logid=5082a1ce-c234-4c2e-92d4-5c5bd5a72854&pageindex=2&pagesize=10


Response

Codes

200 OK Messages found.
400 Bad Request Something wrong with the query parameters.
404 Not Found Log not found.

Example

200
Body
{
    "messages":
        [
            {
                "title": "This is the first test message"
            },
            {
                "title": "This is the second test message"
            },
            ...
        ],
    "total": 21
}

Delete message Enterprise

DELETE/api/v2/messages

Deletes a single message by it's id and logid. If the message is deleted, the request returns a status code 200.

Request

Parameters

logid
required
GUID The id of the log you would like to delete the message from
id
required
string The id of the message you would like to delete.

Example

DELETEhttps://elmah.io/api/v2/messages?id=6707A1B0A79C8E85&logid=5082a1ce-c234-4c2e-92d4-5c5bd5a72854


Response

Codes

200 OK Message deleted.
402 Payment Request Trying to call this endpoint without an Enterprise subscription.
404 Not Found Message not found.

Delete messages Enterprise

DELETE/api/v2/messages

Deletes a list of messages by logid and query. If the messages are deleted, the request returns a status code 200.

Request

Parameters

logid
required
GUID The id of the log you would like to delete the messages from

Example

DELETEhttps://elmah.io/api/v2/messages?logid=5082a1ce-c234-4c2e-92d4-5c5bd5a72854

Body
{
    "query": "This is a test message",
    "from": "2016-05-25T07:00:00+00:00",
    "to": "2016-05-25T08:00:00+00:00",
}

Response

Codes

200 OK Messages deleted.
400 Bad Request Problem with query.
402 Payment Request Trying to call this endpoint without an Enterprise subscription.
404 Not Found Log not found.

Hide message Enterprise

POST/api/v2/messages/_hide

Hides a single message by it's id and logid. If the message is hidden, the request returns a status code 200.

Request

Parameters

logid
required
GUID The id of the log you would like to hide the message from
id
required
string The id of the message you would like to hide.

Example

POSThttps://elmah.io/api/v2/messages/_hide?id=6707A1B0A79C8E85&logid=5082a1ce-c234-4c2e-92d4-5c5bd5a72854


Response

Codes

200 OK Message hidden.
402 Payment Request Trying to call this endpoint without an Enterprise subscription.
404 Not Found Message not found.

Message


Parameters

title
required
String The textual title or headline of the message to log.
application
optional
String Used to identify which application logged this message. You can use this if you have multiple applications and services logging to the same log.
cookies
optional
Key/Value A key/value pair of cookies. This property only makes sense for logging messages related to web requests.
data
optional
Key/Value A key/value pair of user-defined fields and their values. When logging an exception, the Data dictionary of the exception is copied to this property. You can add additional key/value pairs, by modifying the Data dictionary on the exception or by supplying additional key/values to this API.
dateTime
optional
String The date and time in UTC of the message. If you don't provide us with a value in dateTime, we will set the current date and time in UTC.
detail
optional
String A longer description of the message. For errors this could be a stacktrace, but it's really up to you what to log in there.
form
optional
Key/Value A key/value pair of form fields and their values. This property makes sense if logging message related to users inputting data in a form.
hostname
optional
String The hostname of the server logging the message.
queryString
optional
Key/Value A key/value pair of query string parameters. This property makes sense if logging message related to a HTTP request.
source
optional
String The source of the code logging the message. This could be the assembly name.
serverVariables
optional
Key/Value A key/value pair of server values. Server variables are typically related to handling requests in a webserver but could be used for other types of information as well.
severity
optional
String An enum value representing the severity of this message. The following values are allowed: Verbose, Debug, Information, Warning, Error, Fatal
statusCode
optional
Number If the message logged relates to a HTTP status code, you can put the code in this property. This would probably only be relevant for errors, but could be used for logging successful status codes as well.
type
optional
String The type of message. If logging an error, the type of the exception would go into type but you can put anything in there, that makes sense for your domain.
url
optional
String If message relates to a HTTP request, you may send the URL of that request. If you don't provide us with an URL, we will try to find a key named URL in serverVariables.
user
optional
String An identification of the user triggering this message. You can put the users email address or your user key into this property.
version
optional
String Versions can be used to distinguish messages from different versions of your software. The value of version can be a SemVer compliant string or any other syntax that you are using as your version numbering scheme.

Example

Body
{
    "title": "This is a test message",
    "application": "elmah.io Website",
    "cookies": [
        {"key": "Version", "value": "2"},
        {"key": "Language", "value": "English"}
    ],
    "data": [
        {"key": "Hello", "value": "World"},
        {"key": "Foo", "value": "Bar"}
    ],
    "dateTime": "2014-11-28T20:55:26+00:00",
    "detail": "This is a very long description telling more details about this message",
    "form": [
        {"key": "Firstname", "value": "Thomas"},
        {"key": "Lastname", "value": "Ardal"}
    ],
    "hostname": "Webserver01",
    "queryString": [
        {"key": "logid", "value": "f447950c-20a5-48bb-9324-074f58d83df9"},
        {"key": "page", "value": "42"}
    ],
    "source": "System.Web.Mvc",
    "serverVariables": [
        {"key": "SERVER_PROTOCOL", "value": "HTTP/1.1"},
        {"key": "SERVER_PORT", "value": "443"}
    ],
    "severity": "Information",
    "statusCode": 200,
    "url": "http://somedomain.com/some/path",
    "type": "string",
    "user": "info@elmah.io",
    "version": "1.2.3"
}

Query


Parameters

query
required
String The text to search for or Lucene Query Syntax.
from
optional
DateTime The date and time to search from. If you don't provide us with a value in from, we will search from the beginning of time.
to
optional
DateTime The date and time to search to. If you don't provide us with a value in to, we will search to the end of time.

Example

Body
{
    "query": "This is a test message",
    "from": "2016-05-25T07:00:00+00:00",
    "to": "2016-05-25T08:00:00+00:00",
}