> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.umnai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.umnai.com/_mcp/server.

# API reference

Use the API reference when you need exact endpoint paths, request bodies, response schemas, parameters, and examples.

For guided workflows, start with the [guides](/guides). For conceptual background, use the [concepts](/concepts) section.

## Authentication

Most API requests require an access token.

Your integration gets an access token by exchanging API credentials at the authentication endpoint. Use the returned token as a bearer token on subsequent requests.

```bash
Authorization: Bearer ACCESS_TOKEN
```

### Get an access token

### Request

POST [https://api.hi.umnai.com/oauth/token](https://api.hi.umnai.com/oauth/token)

```curl Account Credentials Authentication
curl -X POST https://api.hi.umnai.com/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=62608e08adc29a8d6dbc9754e659f125" \
     -d "client_secret=37b599fa-8a7f-495e-a3d4-1e5f824a522f"
```

```python Account Credentials Authentication
import requests

url = "https://api.hi.umnai.com/oauth/token"

payload = ""
headers = {"Content-Type": "application/x-www-form-urlencoded"}

response = requests.post(url, data=payload, headers=headers)

print(response.json())
```

```javascript Account Credentials Authentication
const url = 'https://api.hi.umnai.com/oauth/token';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/x-www-form-urlencoded'},
  body: new URLSearchParams('')
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Account Credentials Authentication
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hi.umnai.com/oauth/token"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Account Credentials Authentication
require 'uri'
require 'net/http'

url = URI("https://api.hi.umnai.com/oauth/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/x-www-form-urlencoded'

response = http.request(request)
puts response.read_body
```

```java Account Credentials Authentication
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.hi.umnai.com/oauth/token")
  .header("Content-Type", "application/x-www-form-urlencoded")
  .asString();
```

```php Account Credentials Authentication
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.hi.umnai.com/oauth/token', [
  'form_params' => null,
  'headers' => [
    'Content-Type' => 'application/x-www-form-urlencoded',
  ],
]);

echo $response->getBody();
```

```csharp Account Credentials Authentication
using RestSharp;

var client = new RestClient("https://api.hi.umnai.com/oauth/token");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
IRestResponse response = client.Execute(request);
```

```swift Account Credentials Authentication
import Foundation

let headers = ["Content-Type": "application/x-www-form-urlencoded"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.hi.umnai.com/oauth/token")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Response (200)

```json
{
  "access_token": "eyJhbGaiOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCx6Ijg5YzlmMzdhIn0.eyJzdWIiOiI4ZjQxOWE2Zi1lNDUxLTRiYjItYmQ0Ny1kZGIxZjVmYjM1N2MiLCJuYW1lIjoiSm9zZXBoIE1hc2luaSIsImVtYWlsIjoiam9zZXBoLm1hc2luaUB1bW5haS5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwibWV0YWRhdGEiOnsibGFzdFRlcm1zQ2hlY2siOiIyMDI1LTAyLTI4VDE3OjA3OjU2LjU3M1oifSwicm9sZXMiOlsiQWRtaW4iXSwicGVybWlzc2lvbnMiOlsiZmUuYWNjb3VudC1zZXR0aW5ncy5yZWFkLmFwcCIsImZlLmNvbm5lY3Rpdml0eS4qIiwiZmUuc2VjdXJlLioiLCJ1bW5haS5tb2RlbHMuZGVsZXRlLnBlcm1hbnRlbnRseURlbGV0ZSJdLCJ0ZW5hbnRJZCI6ImNmNWIwOTNlLTdmNjUtNDgwZS05ODEwLTdmZWI3ODY0OTIyMiIsInRlbmFudElkcyI6WyJjMDU1MmUzZC00ZWI0LTQyODktOTg2Yi1mMGVkMWU0YWM3OWMiLCJjZjViMDkzZS03ZjY1LTQ4MGUtOTgxMC03ZmViNzg2NDkyMjIiXSwicHJvZmlsZVBpY3R1cmVVcmwiOiJodHRwczovL3d3dy5ncmF2YXRhci5jb20vYXZhdGFyLzA3ZDQ1YmE5Nzk2MDExZGQ5ZmRiZDJiMzkyZmM5NDdkP2Q9aHR0cHM6Ly91aS1hdmF0YXJzLmNvbS9hcGkvSm9zZXBoK01hc2luaS8xMjgvcmFuZG9tIiwiZXh0ZXJuYWxJZCI6bnVsbCwicGhvbmVOdW1iZXIiOm51bGwsInNpZCI6ImJmZmZjZjNmLTE3ODkt4GRhNi1hN2JkLThkZTRkMGUwODYwYiIsInR5cGUiOiJ1c2VyVG9rZW4iLCJhcHBsaWNhdGlvbklkIjoiZmJhMzE3YjQtNmIyMS00NjZhLTlkMjktZDZjZTNlZWEzZWVhIiwiYXVkIjoiODljOWYzN2EtMmQyNC00ZmE2LWJlMTItYjkxOGM4ZmIzZDEzIiwiaXNzIjoiaHR0cHM6Ly9hcHAtaXIwZXhsajh0a3ZnLmZyb250ZWdnLmNvbSIsImlhdCI6MTc3NDU0MDA1MSwiZXhwIjoxNzc3MTMyMDUxfQ.WTbu-NBi9NSxn9y4tusGJIentDWkDWF2uwcGwp3Ms_2e7yxyqJLSjYXgLjj3oZUs-oVbTJaRmFDPK7B5x8eiyUoD7WxhkcOBTwzFMkcQMkVEVCxCO_zeI_xVPz1auxiKmfNEMcToYMpxkiX401b5Oq_59vESpZPvWhsrV-eLxnADsEV8B2hGEmemAcb_64JJIHipyDfpclpznMzirE6KEJ6AEMlE3BedKV2g0Zb_jsBsQNxY-ZH-EgcGYSc8ft8JlhQZCvva32YD8Z2eJV3BIycGsEs9vnMd1RXiEL3ZrJm7T9S_fzKkIQ5d2Qarg9PAdNBOIPYFsb2Y2klkvs-GsQ",
  "token_type": "Bearer",
  "expires_in": 2592000
}
```

Account credentials use `grant_type: "client_credentials"` with a `client_id` and `client_secret`.

Keep API credentials and access tokens secret. Do not expose them in browser code, mobile apps, notebooks, logs, or shared configuration files.

## Make your first request

After you have an access token, call any authenticated endpoint with the `Authorization` header.

### Request

GET [https://api.hi.umnai.com/accounts](https://api.hi.umnai.com/accounts)

```curl
curl https://api.hi.umnai.com/accounts \
     -H "Authorization: Bearer <token>"
```

```python
import requests

url = "https://api.hi.umnai.com/accounts"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.hi.umnai.com/accounts';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hi.umnai.com/accounts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.hi.umnai.com/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.hi.umnai.com/accounts")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.hi.umnai.com/accounts', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.hi.umnai.com/accounts");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.hi.umnai.com/accounts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

Use this request to confirm that authentication works and that your credentials can access the expected accounts.

## Response formats

Most API responses are JSON.

View endpoints often return tabular data using a split-orientation dataframe structure:

```json
{
  "columns": ["column_name"],
  "index": [0],
  "data": [["value"]]
}
```

See the [View response structure](/guides/views/response-structure) guide for how to read view outputs.

## Long-running requests

Some operations may return `202 Accepted` instead of the final result immediately.

When this happens, the response includes a `Location` header. Poll the URL in the `Location` header to retrieve the completed result.

## Errors and troubleshooting

When a request fails, check the status code and response body first.

For troubleshooting, keep the request ID from the response headers when available. Include it when contacting support so the request can be traced more easily.

## Compatibility

The API may add new optional fields, enum values, endpoints, examples, or response columns over time.

When building clients, prefer parsers that tolerate additional fields and columns. Avoid depending on object property order unless the schema explicitly defines a positional structure, such as split-orientation dataframe rows that align with `columns`.