# Testing with API Tools

Before building a full integration, it is useful to explore the Makini API interactively. This guide walks through importing the Makini OpenAPI spec into Postman and making your first authenticated requests.

The same approach applies to other API clients that support OpenAPI imports, such as Insomnia or Bruno.

## Prerequisites

- A Makini account with at least one active [connection](./connections). See [Account setup](./account-setup) if you haven't done this yet.
- [Postman](https://www.postman.com/downloads/) installed.
- A valid access token. See [obtaining a token](#obtaining-a-token) below.

## Import the OpenAPI Spec

Makini publishes an OpenAPI specification that contains all endpoints, parameters, and response schemas.

1. Go to the Makini API docs and click **Export** at the bottom of the page to download the spec file.
2. Open Postman and click **Import** (top left).
3. Select the downloaded file and confirm.

Postman generates a collection with all available endpoints grouped by resource — Connections, Work Orders, Assets, and so on.

## Obtaining a Token

All Makini API requests require a Bearer token scoped to a specific connection. There are two ways to get one for testing:

### Option A — Dashboard (recommended for testing)

1. Navigate to **Connections** in the Makini dashboard.
2. Find the connection you want to test against.
3. Click the **options menu** (⋯) on the right side of the connection row.
4. Select **Generate Token** and copy the token immediately — it is shown only once.

### Option B — Admin API

If you prefer to generate the token programmatically, use the [Admin API authentication](./admin-api-authentication) flow with your Client ID and Client Secret.

## Configure Authentication in Postman

1. Select the imported collection in the left sidebar.
2. Go to the **Authorization** tab.
3. Set the type to **Bearer Token**.
4. Paste your access token into the **Token** field.

All requests in the collection inherit this setting by default, so no per-request configuration is needed.

> If you want to use the full OAuth 2.0 flow directly from Postman, first register `https://oauth.pstmn.io/v1/callback` as a Redirect URI in **Settings > Application Settings** in the dashboard. Then use Postman's **Get New Access Token** button with the Makini authorization URL.

## Set the Base URL Variable

The imported collection uses a `baseUrl` variable. Set it to the v4 endpoint:

| Variable | Value |
| --- | --- |
| `baseUrl` | `https://api.makini.io/v4` |

To set it, open the collection's **Variables** tab and enter the value in the **Current Value** column.

## Make Your First Request

1. Expand the collection and select a request — **List Work Orders** or **List Assets** are good starting points.
2. Click **Send**.

A successful response returns a `200 OK` with a `data` array and a `meta` pagination object:

```json
{
  "data": [
    {
      "id": "makini-uuid-here",
      "_idValue": "WO-10042",
      "_displayValue": "Quarterly pump inspection",
      "_createdAt": "2025-09-15T08:30:00Z",
      "_updatedAt": "2025-10-01T14:22:00Z",
      "_deletedAt": null
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 12,
    "per_page": 50,
    "total": 573
  }
}
```

See [Unified Data Model](./unified-data-model) for a full explanation of standard fields.

## Pagination

List endpoints support pagination via query parameters. Add them in the **Params** tab in Postman:

| Parameter | Description | Default |
| --- | --- | --- |
| `page` | Page number to retrieve | `1` |
| `per_page` | Number of results per page | `50` |

Example request URL with pagination:

```
GET https://api.makini.io/v4/work-orders?page=2&per_page=25
```

Use the `meta.last_page` value from the response to determine how many pages are available.

## Troubleshooting

| Symptom | Likely cause |
| --- | --- |
| `401 Unauthorized` | Token is expired or missing. Regenerate via the dashboard or refresh via the Admin API. |
| `403 Forbidden` | Token is valid but not scoped to the resource you're requesting. Check that the token matches the intended connection. |
| Empty `data` array | The connected system has no records for this endpoint, or the connection is still synchronizing. Check its status on the Connections page. |
| `422 Unprocessable Entity` | Invalid query parameter value (e.g., non-numeric `page`). |