Skip to main content

API Endpoints/Data

M
Written by Mitchell Lane

AskFRED's new API system currently allows for two types of access: (1) access to your own personal data, and (2) access to basic public tournament information for programmatically searching for events.

The base URL for all API requests is the standard https://www.askfred.net/api/v1/

API Request Authentication

AskFRED uses Bearer tokens for authentication. This requires you to add a header to each request of the name Authorization with the value of Bearer 1234abcd - replacing "1234abcd" with your own API key. Note the single space between "Bearer" and the API token. This header is required on every request.

All of the API requests made will be against the user authenticated with this API token.

Rate Limits and Rules

API tokens are also tracked and rate limited. Bad behavior will result in a ban. If you're unsure if you're doing something considered "bad behavior", reach out to support to ask about it. An easy example of "bad behavior" would be to try and fetch all data in our platform in order to produce a competitor.

Our current rate limit exponential backoff scheme looks like this:

  • 25 requests per 5 seconds

  • 50 requests per 25 seconds

  • 75 requests per ~2 minutes

  • 100 requests per ~10 minutes

  • 125 requests per ~50 minutes

These are additive/layered and designed for us to ensure systems stability around the new API while we roll it out for the first time in alpha. Another way to think about these are that you can do about 125 requests per hour, and if you make those requests too quickly inside that hour, you'll get slowed down further. For example, if you burn all 125 requests in the first 11 minutes, you'll be waiting another 39 minutes until you can make more requests.

If you're throttled, we will return a 429 error. In later releases, we'll likely be adding more data to the response for well-behaved users to understand how long they have to wait to get un-throttled.

We also have some undisclosed rate limiting protection in place for anyone who is attempting to brute force the API. This is higher than the limits above, though not by all that much in order to ensure we catch people trying multiple different API keys. If you hear the 429 error and respect it, you won't get caught in this rule. Hitting these rules will temp ban you for an uncomfortably long period of time and will likely require support to intervene on your behalf. We realize this would mean building a third party platform is difficult, so if you are trying such a thing, lets talk.

IDs

AskFRED uses uuids for primary key IDs. Any ID provided via the API are also usable in the public website - for example, a Tournament if ID abcdefg would also be available via public website at https://www.askfred.net/tournaments/abcdefg

Introspection API Endpoints

The following API requests allow introspection of your own personal data:

  • get '/me': this returns a small amount of data about the authenticated user.

  • get '/me/bouts': returns all bouts fenced by any fencer associated with this user.

  • get '/me/bouts/:id': returns the details of any specific bout by id

  • get '/me/events': returns all events this user's fencers have participated in

  • get '/me/events/:id': returns details of an event by id that is returned by the previous endpoint.

  • get '/me/tournaments': returns all tournaments this user's fencers have participated in.

  • get '/me/tournaments/:id': returns details of an tournament by id that is returned by the previous endpoint.

For those who have multiple fencers on their account the following endpoints can be used to narrow the responses down to just one fencer:

  • GET /me/fencers - Returns all fencers associated with the authenticated user

  • GET /me/fencer/:fencer_id/bouts - Returns bouts scoped to a specific fencer

  • GET /me/fencer/:fencer_id/events - Returns events scoped to a specific fencer

  • GET /me/fencer/:fencer_id/tournaments - Returns tournaments scoped to a specific fencer

Public Tournament API Endpoints

  • get '/tournaments': returns all tournaments

  • get '/tournaments/:id': returns information related to a tournament

  • get '/tournaments/:id/events': returns all events from a specific tournament

Query Parameters

Almost all API list-based endpoints respond to various search parameters. Get parameters are all lower-case, and any spaces are instead the underscore(_) character.

Below is a list of fields and suffixes (and a few custom/special query paramters). You can create a query parameter as such, which combines the fenced_at field with the _gteq suffix: ?fenced_at_gteq=01-01-2025 If provided to the bouts endpoint this would return all bouts fenced on or after January 1 2025.

Number and Date field based suffixes

Number and date based params all have the same param suffixes:

  • _eq - equality

  • _not_eq - not equal

  • _lt - less than

  • _lteq - less than or equal to

  • _gt - greater than

  • _gteq - greater than or equal to

String field based suffixes

  • _eq - equality

  • _not_eq - not equal

  • _matches - regex match

  • _does_not_match - regex doesn't match

  • _present - opposite of _blank

  • _blank - is blank, null, empty string, etc?

  • _start - starts with provided value

  • _end - ends with provided value

  • _in - given a list of strings, is the value one of the list?

  • _not_in - the opposite of _in

Bout-specific queries

For any bout list endpoints, you can also query the following:

  • event_id_eq - this will restrict results to only the event ID specified.

  • tournament_id_eq - this will restrict results to only the tournament ID specified.

  • fenced_at_* - this is a date-based field that uses the date suffixes above.

  • weapon_* - this is a string-based field that uses the string suffixes above.

  • page - if you don't specify this, we default to the first page of the list.

  • per_page - the number of results to return per query. If you don't specify this, we default it to 10. Maximum is 50.

Event-specific queries

For any event list endpoints, you can query the following:

  • close_of_reg_* - date field

  • age_limit_* - string field

  • authority_* - string field

  • gender_* - string field

  • rating_* - string field

  • rating_predicted_* - string field

  • rating_limit_* - string field

  • weapon_* - string field

  • page - if you don't specify this, we default to the first page of the list.

  • per_page - the number of results to return per query. If you don't specify this, we default it to 10. Maximum is 50.

Tournament-specific queries

For any tournament list endpoints, you can use the following:

  • name_eq - string field, only supports equality

  • end_date_* - date field

  • prereg_close_* - date field

  • prereg_open_* - date field

  • start_date_* - date field

  • page - if you don't specify this, we default to the first page of the list.

  • per_page - the number of results to return per query. If you don't specify this, we default it to 10. Maximum is 50.

  • latitude and longitude - if both of these are present, search results are limited to a 100 mile radius around the given coordinates. This radius is not currently configurable.

API Response Schema

All APIs conform to the JSON-API standard. The content of each response is currently in flux and won't be documented here.

Did this answer your question?