Exceptionless API Usage and Overview

Exceptionless APISo you’ve been using Exceptionless for a while, but you wish you had a different dashboard, or maybe you’d like to integrate event data into one of your apps. No problem, just use the API!

Through our adventures while building Exceptionless, we’ve kept open source, automation, and ease of use in mind. With that, we think our API, which utilizes Swagger and Swashbuckle to automatically generate, update, and display documentation (which means it works automatically on self-hosted environments), is a great resource for our users that want to get their hands dirty and use Exceptionless data to roll their own tools, dashboards, etc.

Lets take a closer look at the API, how to use it, and some quick examples of what can be done.

Start Using the Exceptionless API

Accessing the API

To access the Exceptionless API, visit https://api.exceptionless.io and click on the “API Documentation” link to be taken to the API documentation.

Get Your User Scoped Token

Tokens are used to access the api and have roles (scopes). When you authenticate via the login controller action, you are getting a token that impersonates your user so it has the same roles as your user account (e.g., client and user).

Go to Auth controller action and enter your login credentials.

You can enter JSON into the model field, or you an click the yellow box on the right to pre-populate the field with acceptable JSON fields. Just replace the values that you want to specify and remove the fields you don’t need, like invite token.

Exceptionless API Get User Scoped Token
Enter account credentials to get user scoped token.

Click “Try it out!” and generate your token. Take note of the response messages section above the button, as it details the possible codes that would be returned in the event of an error (e.g. 401 if the user name or email address was incorrect).

Retrieve Exceptionless User Scoped Token
Copy your user scoped token that you just generated.

You can see from the response that it returned our token from the request url above. Take your generated token and put it in the “api_key” field at the top of the page and click “Explore.” This authorizes you via bearer authentication, authenticates you to the rest api, and allows you to call controller actions.

Add Exceptionless User Scoped Token
Add your token in the api_key field at top of page and click “Explore”

Get a New Token

Now, we’ll get a new token for the project we want to work on and assign it a user role (scope) of “user.” We want to get a new user scoped token because we want to do more than just post events (client scoped tokens only allow you to post events), we want to retrieve them. Creating a new token also allows us to revoke the token later.

First, get your project ID from the Exceptionless Dashboard. It can be found in the URL of that project’s dashboard.

Get Exceptionless Project ID
Get Project ID

Now, we’ll navigate to Tokens > POST /api/v2/projects/{projectId}/tokens, enter our Project ID, and set up our token to include the user scope and a quick note.

Create Exceptionless Token
Enter project ID and create a new token with scope “user.”

Next, we’ll click “Try it out!” and generate our new token id.

Get new Exceptionless Token ID
Copy your new token id and paste it into the api_key field at the top of the page and click “Explore” again.

Now, once again, copy this new token and place it in the “api_key” field at the top of the page and click “Explore.” Now everything we do will be authenticated to this new user token you’ve just created.

Posting an Event

Now, lets post an event with a reference ID that we’ll use for a few other examples.

First, navigate to Event > POST /api/v{version}/events

Exceptionless API Post Event
Navigate to Event > POST /api/v{version}/events

You’ll see a few basic examples of events and some explanation of the resource in this panel. Make sure to give it a read. For this example, we’ll use a simple log event, with a brief message, and add a reference ID to it. Note that you must also enter the current API version in the “version” field.

When we click “Try it out!” and get a 202 response code, we know we’ve created an event.

Exceptionless API Create Event Example
Create your event and enter API version
Exceptionless API Created Event
Successful Event Creation

Get Event by Reference ID

If we want to get the event we just created by it’s reference_id, we can navigate to Event > GET /api/v2/events/by-ref/{referenceId}, enter that reference ID, and get back the details of the event.

Get Exceptionless Event by ReferenceID
Navigate to Event > GET /api/v2/events/by-ref/{referenceId} and enter reference ID

Getting the Event via a Search Filter

Another example of getting an event may include using the reference ID or another search filter we just created and getting all by a reference filter. You can use any search filter in the filter parameter.

To do so, navigate to Event > GET /api/v2/events and use the reference term to filter events by the reference ID.

Exceptionless API Get All Filter Search
Navigate to Event > GET /api/v2/events and user the filter field to search for the reference ID

Results

Exceptionless API Get Al Filter Search Results
Get All results

Get Organizations and Projects

Naturally, we can get all the organizations or projects associated with the current authorized token, as well.

Organizations

Navigate to Organization > GET /api/v2/organizations and click “Try it out!”

Exceptionless API Get Organizations
Navigate to Organization > GET /api/v2/organizations and click “Try it out!”
Exceptionless API Get Organization Results
Get Organizations Results

Projects

Navigate to Project > GET /api/v2/projects and click “Try it out!”

Exceptionless API Get Projects
Navigate to Project> GET /api/v2/projects and click “Try it out!”
Exceptionless API Get Projects Results
Get Projects Results

How to Authenticate to the API

1. Bearer Authentication

The api documentation uses bearer authentication to authenticate to the API. You can do this in your apps too by specifying a bearer authorization header with your token as shown below.

Exceptionless Bearer Authentication
Bearer Authentication Example

2. Authenticate via the Query String

Everything we’ve shown you today can be easily and cleanly accessed via a URL query string and your access token.

For example, if we want to view our organizations, we simply navigate to https://api.exceptionless.io/api/v2/organizations, add the query string “?access_token={token}” and press enter to get the data.

Exceptionless Query String API Authentication
Query String API Authentication

Let Us Know What You Think!

We’ve tried to make the API as easy and intuitive to use as possible, but we’re always open to feedback and comments, so please let us know what could be better, easier, faster, etc.

And, of course, if you have any questions about the API, please leave a comment here, send us an in-app support message, or simply submit the website contact form.