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. See Account setup if you haven't done this yet.

Postman installed.

A valid access token. See obtaining a token below.

Import the OpenAPI Spec

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

Go to the Makini API docs and click Export at the bottom of the page to download the spec file.

Open Postman and click Import (top left).

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)

Navigate to Connections in the Makini dashboard.

Find the connection you want to test against.

Click the options menu (⋯) on the right side of the connection row.

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 flow with your Client ID and Client Secret.

Configure Authentication in Postman

Select the imported collection in the left sidebar.

Go to the Authorization tab.

Set the type to Bearer Token.

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

Expand the collection and select a request — List Work Orders or List Assets are good starting points.

Click Send.

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

{
  "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 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`).

Testing with API Tools

Prerequisites#

Import the OpenAPI Spec#

Obtaining a Token#

Option A — Dashboard (recommended for testing)#

Option B — Admin API#

Configure Authentication in Postman#

Set the Base URL Variable#

Make Your First Request#

Pagination#

Troubleshooting#