Schema

The API responses from v1 all extend this basic response schema. The schema is defined in Typescript.

interface Base_ApiV1 {
  _self: Link; // This is the Link of the current endpoint
  _version: "v1"; // The Api version
  _description: string; // A short desciption of what the endpoint does
  _links: Array<Link>; // Hyperlinks to navigate to from here
}

The base response is implemented by all endpoints. It serves to make the API self descriptive.

All endpoints provide hyperlinks to help navigate the API and will list the available HTTP Request methods that are supported.

interface Link {
  href: string;
  methods: Array<Methods>
}

enum Methods {
  GET = "GET",
  POST = "POST",
  DELETE = "DELETE",
  PUT = "PUT",
}

Errors

The API will return errors using this generic interface. If the response status is not 200, then you can expect to find an error message in the response.

interface ErrorResponse extends Base_ApiV1 {
  error: Error;
}

interface Error {
  message: string; // The error message
  status: number; // The returned error code
  timestamp: string; // The timestamp, it is always UTC time
}

Pagination

Endpoints that return multiple results implement a Pagination interface that will let you query for lists paginated. You can identify these endpoints as they don't support [slug] parameter, which is used for fetching data individually and we will discuss it later.

The endpoints that support pagination will return these parameters:

interface PaginationResponse_ApiV1 {
  current_page: number; // The current page returned
  total_pages: number; // The total pages available for the current page size!
  page_size: number; // Defaults to 10. This is used together with current_page and total_pages to determine page content
  sort_by: string; // The column that is currently sorted in this response
  sort_direction: string; // The ordering of the sorted column. Values can be  "ASC" or "DESC"
  sortable_columns: Array<string>; // This returns the list of valid column names that can be sorted
}

When using Pagination, the request url can contain the following query parameters:

interface PaginationSearchParams_ApiV1{
  current_page: number | undefined;  // The current page we are requesting, defaults to 1 if undefined 
  page_size: number | undefined;  // The size of the pages, used to override the default value : 10
  sort_by: string | undefined; // The column name to sort by, defaults to "created_at" when undefined
  sort_direction: string | undefined; // The ordering for the sorted column. Values can be "ASC" or "DESC" defaults to "DESC" if undefined"
}

If any of these are missing from the request, the default parameters are used.

A paginated GET request would have the following URL parameters:

https://debitllama.com/api/v1/accounts?current_page=1&page_size=20&sort_by=network_id&sort_direction=DESC

This will fetch a page with a custom page size, sorted by network_id

Filtering is available when fetching collections. The applied filters are returned as a collection of filters

filters: Array<Filter>

interface Filter {
  parameter: string;
  value: string;
}

availableFilters: Array<string>

While available filters are returned as an array of strings!

To use a filter you must use the filter query parameter in the URL and JSON encode your parameters

Example:

const filter = JSON.stringify({
  network_id : "0x405", 
  account_type : "VIRTUALACCOUNT", 
  closed : false, 
});

https://debitllama.com/api/v1/accounts?=filter${filter}

This request will return all open virtual accounts on the network 0x405 using the default pagination