Skip to content

API

Unity exposes a REST API so that you can read and manage your Unity data from your own tools and scripts. This page explains how to find the API documentation, authenticate, and make your first requests.

Base URL

Production base URL:

https://unity.thebadjr.com

All API paths below are relative to the API prefix:

https://unity.thebadjr.com/api/unity/v1

Documentation and tools

Resource Location
Swagger UI (interactive reference) https://unity.thebadjr.com/swagger
OpenAPI specification (JSON) https://unity.thebadjr.com/bl-backpack/api/openapi.json
Postman collection https://unity.thebadjr.com/bl-backpack/api/bl-backpack.postman_collection.json
Postman environment https://unity.thebadjr.com/bl-backpack/api/bl-backpack.postman_environment.json

Use Swagger UI to browse every endpoint and its fields. Use the OpenAPI file if you want to generate a client or import the API into another tool.

Using the Postman collection

  1. In Postman, choose Import and import both the collection and the environment files above.
  2. Select the Unity API environment.
  3. Set the environment variables:
    • unity_base_url: https://unity.thebadjr.com
    • unity_username: the email address of your Unity user
    • unity_password: your Unity password
  4. Run Auth > Login. The returned token is stored in unity_token and used by the other requests.

Do not share your password or token. Clear unity_token when you finish, or run Auth > Logout.

Authentication

The API uses bearer tokens.

  1. Log in with your email address and password:

    ```http POST /api/unity/v1/auth/login Accept: application/json Content-Type: application/json

    { "email": "you@example.com", "password": "your-password", "device_name": "my-script" } ```

    device_name is optional and helps you identify the token later.

  2. The response contains your token under the token key.

  3. Send the token with every other request:

    http Authorization: Bearer <token>

Other auth endpoints:

Method Path Purpose
POST /api/unity/v1/auth/refresh Issue a new token for the current session
POST /api/unity/v1/auth/logout Revoke the current token

OAuth 2.1

Unity also provides an OAuth 2.1 authorization server (authorization code with PKCE, refresh tokens and client credentials). Use it when a third-party application needs to act on a user's behalf without handling their password.

Path Purpose
https://unity.thebadjr.com/.well-known/oauth-authorization-server Server metadata
https://unity.thebadjr.com/oauth/authorize Authorization endpoint
https://unity.thebadjr.com/oauth/token Token endpoint
https://unity.thebadjr.com/oauth/register Dynamic client registration

Tokens issued through OAuth are used as bearer tokens on every other endpoint, exactly like tokens from the login endpoint.

Making requests

The API follows the JSON:API format for resource endpoints. Send these headers on every resource request:

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Authorization: Bearer <token>

Content-Type is only needed when sending a body (create and update requests).

Example: list clients

GET /api/unity/v1/client
Accept: application/vnd.api+json
Authorization: Bearer <token>

Every resource follows the same pattern. Replace client with the resource you need, as listed in the OpenAPI specification or Swagger UI:

Method Path Operation
GET /api/unity/v1/{resource} List
GET /api/unity/v1/{resource}/{id} Show one record
POST /api/unity/v1/{resource} Create
PATCH /api/unity/v1/{resource}/{id} Update
DELETE /api/unity/v1/{resource}/{id} Delete

Successful responses are:

  • 200 for list, show and update
  • 201 for create, with a Location header pointing to the new record
  • 204 for delete

Listing records

List endpoints support these query parameters:

Parameter Example Meaning
page[number] page[number]=2 Page to return
page[size] page[size]=50 Records per page (maximum 100)
sort sort=-name,id Comma-separated columns; prefix with - for descending
filter[field] filter[name]=Acme Filter by a column value

Page size defaults to 25 and the maximum is 100.

Errors

Errors return a non-2xx status with a JSON:API error body. Common causes:

Status Meaning
400 The request is invalid.
401 Missing or invalid token. Log in again or refresh the token.
403 Not allowed, or the resource is not available through the API.
404 The resource does not exist.
409 The resource type or ID does not match the URL, or the change was refused.
422 Validation failed. source.pointer names the field, or source.parameter names the query parameter.

Tips

  • Start with GET /api/unity/v1/client to confirm your token works.
  • Use Swagger UI to see the required fields for each create and update request.
  • Keep tokens secret. Treat them like passwords and revoke them with logout when they are no longer needed.