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
- In Postman, choose Import and import both the collection and the environment files above.
- Select the Unity API environment.
- Set the environment variables:
unity_base_url:https://unity.thebadjr.comunity_username: the email address of your Unity userunity_password: your Unity password
- Run Auth > Login. The returned token is stored in
unity_tokenand 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.
-
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_nameis optional and helps you identify the token later. -
The response contains your token under the
tokenkey. -
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:
200for list, show and update201for create, with aLocationheader pointing to the new record204for 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/clientto 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.