API

Error & Crash Reporting API

The Raygun API is REST-oriented and uses JSON for sending and receiving. You can manually publish errors to Raygun using this interface, or use it to create your own provider. All calls are made over HTTPS.

API Endpoint

https://api.raygun.com

Headers

The header must contain "X-ApiKey" with a value that is a valid Raygun Crash Reporting API key (available under Crash Reporting - Application Settings).

URI Summary

Crash Reporting error payloads

POST https://api.raygun.com/entries

The body of the message should be JSON with the following structure:

{
	// Date and time that the error occurred in ISO-8601 format
	"occurredOn": "2015-09-08T01:55:28Z",
	"details": {
		// The name of machine this error occurred on
		"machineName": "ServerMachine1",
		// Client defined error grouping key. Must be 1-100 chars, ideally the result of a hash function e.g MD5
		"groupingKey": "ErrorGroup",
		// The version number of your application.
		"version": "1.0.0.1",
		// Information about the client library you are using for talking to the Raygun API
		"client": {
			// Name of the library
			"name": "Example Raygun Client",
			// Version of the library
			"version": "0.0.0.1",
			// URL where the client can be downloaded or viewed
			"clientUrl": "https://raygun.com/docs/integrations/api"
		},
		// Information about the error itself
		"error": {
			// The error that caused the outer error.
			// Has all the same properties as the "error" object that contains it.
			"innerError": {},
			// Data contained in the error object
			"data": {
				"example": 5
			},
			// The name of the error
			"className": "ErrorClass",
			// The error message
			"message": "An error occurred",
			// The collection of stack traces.
			// The first one in the list should be the highest on the stack
			"stackTrace": [
			{
				// The line number of this stack frame
				"lineNumber": 55,
				// The name of the class this stack frame is in
				"className": "BrokenService",
				// The column of the file that this stack frame is in
				"columnNumber": 23,
				// The name of the file this stack frame is in
				"fileName": "BrokenService.cs",
				// The name of the method this stack frame is in
				"methodName": "BreakEverything()"
			}]
		},
		// Information about the environment at the time of the error.
		// Each of these properties are optional
		"environment": {
			// The number of processors in the machine
			"processorCount": 4,
			// The version of the operating system this app is running on
			"osVersion": "Windows 10",
			// The width of the window
			"windowBoundsWidth": 2560,
			// The height of the window
			"windowBoundsHeight": 1440,
			// The width of the browser window
			"browser-Width": 2560,
			// The height of the browser window
			"browser-Height": 1440,
			// The width of the screen
			"screen-Width": 2560,
			// The height of the screen
			"screen-Height": 1440,
			// The scale of the screen
			"resolutionScale": 1.0,
			// Color depth of the screen
			"color-Depth": 24,
			// The orientation of the screen
			"currentOrientation": "Landscape",
			// The type of CPU in the machine
			"cpu": "Intel(R) Core(TM) i5-2500 CPU @ 3.30GHz",
			"packageVersion": "package version",
			// CPU architecture (ARMv8, AMD64, etc)
			"architecture": "ARMv7-A",
			// Device manufacturer
			"deviceManufacturer": "Nokia",
			// Device model
			"model": "Lumia 920",
			// Total RAM in MB
			"totalPhysicalMemory": 1024,
			// Available RAM in MB
			"availablePhysicalMemory": number,
			// Total Virtual Memory in MB - RAM plus swap space
			"totalVirtualMemory": number,
			// Available Virtual Memory in MB
			"availableVirtualMemory": number,
			// Free disk space in GB
			"diskSpaceFree": [50000.52, 2000.104],
			// Name of the device (phone name for instance)
			"deviceName": "Nexus 7",
			// Locale setting of the system
			"locale": "en-nz",
			// Number of hours offset from UTC
			"utcOffset": -12,
			// The browser manufacturer
			"browser": "Mozilla",
			// The browser name
			"browserName": "Netscape",
			// The full user agent string
			"browser-Version": "5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.65 Safari/537.36",
			// OS Name
			"platform": "Win32"
		},
		// Tags that should be applied to the error
		// These will be searchable and filterable on the dashboard.
		"tags": ["tag1", "tag 2", "tag-3"],
		// Any custom data you would like to attach to this error instance.
		// You can search on data entered here.
		"userCustomData": {
			"domain": "WORKPLACE",
			"area": "51"
		},
		// Information about the HTTP request being processed when the error occurred.
		// Only useful in a web environment obviously.
		"request": {
			// The hostName portion of the URL being requested.
			"hostName": "https://raygun.io",
			// The path portion of the URL being requested
			"url": "/docs/integrations/api",
			// The HTTP method used to request the URL (GET, POST, PUT, etc)
			"httpMethod": "POST",
			// The IP address of the client that initiated the request
			"iPAddress": "127.0.0.1",
			// The query string portion of the URL
			"queryString": {
				"q": "searchParams"
			},
			// The form parameters sent through with the request. Not form encoded.
			"form": {
				"firstName": "Example",
				"lastName": "Person",
				"newsletter": true
			},
			// The HTTP Headers sent as part of the request
			"headers": {
				"Referer": "www.google.com",
				"Host": "raygun.io"
			},
			// The raw request body. Don't include form values here.
			// See the notes for more information
			"rawData": "{\"Test\": 5}"
		},
		// Information about the response that will be sent back to the client.
		"response": {
			// The HTTP status code that will be sent back to the client
			"statusCode": 500 
		},
		// Information about the user that caused the error
		"user": {
			// Unique identifier for the user
			"identifier": "123456789",
			// Flag indicating if the user is anonymous or not
			"isAnonymous": false,
			// User's email address
			"email": "test@example.com",
			// User's full name
			"fullName": "Test User",
			// User's first name (what you would use if you were emailing them - "Hi {{firstName}}, ...")
			"firstName": "Test",
			// Device unique identifier. Useful if sending errors from a mobile device.
			"uuid": "783491e1-d4a9-46bc-9fde-9b1dd9ef6c6e"
		}
	}
}

HTTP Status Codes

202 OK - Message accepted.

400 Bad message - could not parse the provided JSON. Check all fields are present, especially both occurredOn (ISO 8601 DateTime) and details { } at the top level.

403 Invalid API Key - The value specified in the header X-ApiKey did not match with a user.

413 Request entity too large - The maximum size of a JSON payload is 128KB.

429 Too Many Requests - Plan limit exceeded for month or plan expired

Notes

  • OccurredOn must be present, and is a DateTime string in the ISO 8601 format, in the UTC timezone. This is of the format: 1970-12-31T23:50:59Z

  • The maximum size of the body is 128KB. Payloads larger than this will be discarded.
  • For the field details.request.form, we request that you truncate the names and values to 256 characters each. For rawData, this should be truncated to 4096 bytes.

  • rawData is to be set in the case where the method is non-GET, and the Content-Type is not text/html and not application/x-www-form-urlencoded.

  • There must be at least one details.error, and its stacktrace must have its linenumber set. The other fields can be empty.

  • details.request.form should be the raw form data available from a request-type object when the HTTP method is 'POST' and the Content-Type is 'application/x-www-form-urlencoded'.

  • For the details.environment fields where that data is unavailable from your language, framework or environment, these can safely be absent from the payload (or set to null).

  • User: identifier should be a string representation of the currently logged in user - something that uniquely identifies them in your app. If you set any user properties, you should at least set this one.

  • User: isAnonymous should be set to true if the user is not actually logged in to your app. This is to separate them from the "user info not provided" case.

  • User: uuid should be a device dependent identifier - most mobile device frameworks will give you an identifier of some sort to use here.

Change log

  • 20th Feb 2016 - Updated API endpoint to api.raygun.com from api.raygun.io
  • 28th May 2015 - Add more information about user object. Remove old context object as context.identifier has been rolled into user.uuid.
  • 6th November 2013 - Removed request.httpStatusCode and added response.statusCode.

Documentation missing?

If we don't have documentation about your desired topic, send us a message and we'll create it for you.