arrow_backKnowledge base rocket_launchGeneral

How to use the Perno API?

A guide to where and how to open the API documentation, getting your API token, what your first request looks like, and how endpoints are organized by product.

Perno exposes a REST API at https://perno.io/api/v1/ so you can integrate its products directly instead of using the dashboard. This guide covers where to find the documentation, how to get and use your API token, what a request/response looks like, and how endpoints are organized across Perno's products.

How to find the documentation

You can reach the API documentation two ways: from Perno's landing page, or from inside the logged-in dashboard.

From the landing page

From the logged-in dashboard

  • Sign in to the Perno dashboard.
  • Click your initials in the top-right corner to open the account menu.
  • Select API access

  • Near the bottom of the page, in the Documentation section, click Open API reference - next to it you'll also find the API base URL field.

Both paths lead to the same documentation at perno.io/api/v1/reference/. It lists every endpoint with its parameters, an example request, and an example response, grouped in a searchable sidebar by product.

The same specification is also available as:

  • Redoc - a single-page, read-only rendering of the whole API.
  • Swagger - an interactive view where you can send requests directly from the browser.
  • The raw OpenAPI schema - useful if you want to generate a client library for your language, or import the API into a tool like Postman or Insomnia.

Where to find your API keys

Only the account owner can see and generate the API token:

  • Sign in to the Perno dashboard.
  • Click your initials in the top-right corner to open the account menu - next to API access you'll also find Company data, Merchant accounts, and Your subscriptions, among others.
  • Select API access

  • In the API token section, click Show token to reveal it, or go straight to Copy token to copy it to your clipboard.

If you're not the owner, this menu item won't appear for you - ask your organization's account owner to share or manage API access instead.

Treat this token like a password. Do not include it in browser code, public repositories, screenshots, or support messages.

Send the token with every protected request in the Authorization header - the same example is shown right there on the API access page, under How to authenticate:

Authorization: Token YOUR_API_TOKEN

Making your first request

The documentation's Quick start section has a ready-to-run example that calls the health check endpoint:

export PERNO_API_TOKEN="YOUR_API_TOKEN"
curl "https://perno.io/api/v1/health_check" \
  -H "Authorization: Token $PERNO_API_TOKEN"

If the token is valid, you'll get back a successful JSON response. If it's missing, wrong, or expired, every protected endpoint returns the same 401 error instead - a quick way to confirm your token is set up correctly before building anything on top of it.

Endpoints are organized by product

The docs sidebar groups endpoints the same way the dashboard groups contexts (see What is context in Perno?) - so the product you'd select in the dashboard is the same section you'll find its endpoints under:

  • Core resources - the health check and the OpenAPI schema, available regardless of product.
  • Orchestration - payment links, merchant accounts, and payment methods, for processing payments through Perno Orchestration.
  • Perno Commerce - everything related to a store: categories, producers and products, plus company-directory data such as companies, countries, cities, states, services and specializations.

Perno Commerce endpoints are scoped to a specific store, so list and detail requests take a store_id query parameter identifying which of your stores the request applies to.

The same REST conventions apply everywhere

Regardless of product, resources in the API follow the same pattern, so once you've used one endpoint the rest behave the same way:

  • GET a collection to list records, or a single record's URL to retrieve its details.
  • POST to create a new record.
  • PUT to replace a record entirely, or PATCH to update only the fields you send.
  • DELETE to remove a record.

Example: creating a payment link

This is what a real request/response pair looks like, using the Orchestration endpoint for creating a hosted payment link:

curl -X POST "https://perno.io/api/v1/payment_links/" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_account": 1,
    "amount": "10.00",
    "currency": "USD",
    "customer_email": "[email protected]",
    "trx_id": "123"
  }'

A successful call returns 201 with the created resource:

{
  "payment_hash": "string",
  "merchant_account": 1,
  "trx_hash": "string",
  "trx_id": "string",
  "amount": "string",
  "customer_email": "string",
  "one_time_link": true,
  "used": true
}

Response and error codes

Every endpoint returns JSON and uses the same status codes across products:

  • 200 - the request succeeded and the response body contains the requested resource or list.
  • 201 - a new resource was created successfully.
  • 400 - validation error; the response body contains field-level errors or a detail message, so check the request fields and parameter values.
  • 401 - the token is missing, invalid, or expired; send a valid Authorization header.

Ready to put this knowledge into practice?

Create your Perno workspace and turn these instructions into a working process for your business.

Start building Talk to our team