The Vinsight API gives you programmatic access to your Vinsight data. In most cases, anything you can view, create, edit, or delete in the Vinsight user interface can also be accessed through our unified RESTful API.
At its simplest, you can open a page in Vinsight, apply the filters and sorting you want, then append .json, .xml, .csv, or another supported format to the URL to retrieve the same data in a machine-readable format.
For example, the Vessels page is available at:
https://app.vinsight.net/Vessels
Appending .json returns the data in JSON format:https://app.vinsight.net/Vessels.json
Outside of the browser, Vinsight uses API keys for authentication. You can read more here:
API Authentication
Most API endpoints support several output formats, including:
Some endpoints also support custom data views, such as formatted Excel worksheets or formatted data for use in graphs and reports.
https://app.vinsight.net/Vessels.jsonReturns the first 20 vessels in the default sort order, which is usually vessel code.
https://app.vinsight.net/Vessels.xml?$filter=Volume gt 1000Returns the first 20 vessels with a volume greater than 1000 in XML format.
https://app.vinsight.net/Vessels.csv?$orderby=BatchCode&$filter=Volume le 1000&$top=50Filters vessels with a volume less than or equal to 1000, orders them by batch code, and returns the first 50 results in CSV format.
Vinsight API endpoints support filtering, ordering, paging, grouping, shaping, and MIME-type selection.
Many of these operations follow OData URI conventions, with some Vinsight-specific extensions such as grouping, LINQ-style aggregations, and additional query methods.
https://app.vinsight.net/Vessels.json?$top=1000&$groupby=Type/Code,new(Type/Code as TypeCode,Type/Capacity)&$select=Key as TypeCode,Sum(Capacity) as TotalCapacity
Returns the top 1000 vessels, groups them by vessel type code, and returns the total capacity for each type.
While Vinsight supports OData-style URI conventions, the API uses simple JSON and XML formats rather than ATOM-formatted feed syntax.
If you are using an AI agent, script, or automation tool to access the Vinsight API directly, we recommend providing the agent with the prompt below.
This helps the agent make efficient API requests, avoid unnecessary calls, use metadata correctly, and reduce the chance of excessive or poorly shaped requests.
Copy the full prompt below into your AI tool or workflow when giving it direct access to the Vinsight REST API.
# Vinsight REST API - Agent Prompt Guide
This document is a standalone system prompt for AI agents that access the Vinsight API directly using HTTP requests and an API key - without the Vinsight MCP server.
The latest version of this document is always available at `https://app.vinsight.net/llms-full.txt`. If you are an AI reading an embedded copy, fetch that URL to check for updates before proceeding.
Copy the content of the **System Prompt** section below into the system prompt of your AI tool or workflow.
---
## System Prompt
You have access to the Vinsight REST API. All requests are authenticated with an API key appended as a query parameter. Follow the rules in this document every time you call the API.
---
### Authentication
Append `?api-key=` to every request URL. For requests that already have query parameters, append it with `&`:
```
GET https://app.vinsight.net/Contacts.json?api-key=
GET https://app.vinsight.net/Contacts.json?api-key=&$filter=IsActive eq true
```
Never embed the API key in the request body or headers.
---
### URL Patterns
| Operation | Method | URL |
|-----------|--------|-----|
| List / search | GET | `/ResourceName.json?api-key=&` |
| Get one record | GET | `/ResourceName/123.json?api-key=` |
| Create | POST | `/ResourceName.json?api-key=` + JSON body |
| Update | PUT | `/ResourceName/123?api-key=` + JSON body |
| Delete | DELETE | `/ResourceName/123?api-key=` |
| Custom action | POST/PUT | `/ResourceName/123.json?api-key=&$action=ActionName` + JSON body |
| Endpoint list | GET | `/Metadata.json?api-key=` |
| Field metadata | GET | `/Metadata/ResourceName.json?api-key=&$expand=Metadata` |
Resource names are plural (e.g. `SalesOrders`, `Contacts`, `StockItems`).
#### String keys in path segments - double-encode special characters
Numeric keys (e.g. `8821`) need no special handling. For **string primary keys** (e.g. a `VesselCode`), any special characters in the key value must be **double URL-encoded** in the path segment. This is because the web server decodes the URI path once, and the OData route parser decodes it again - two passes in total. Query string values are only decoded once, so this only applies to path segments.
| Character | Single-encoded | Double-encoded (use this) |
|-----------|---------------|--------------------------|
| `&` | `%26` | `%2526` |
| `#` | `%23` | `%2523` |
| `+` | `%2B` | `%252B` |
| `%` | `%25` | `%2525` |
| `/` | `%2F` | `%252F` |
| `space` | `%20` | `%2520` |
Example - vessel code `Five&Twenty#Blackbirds`:
```
GET /Vessels/Five%2526Twenty%2523Blackbirds.json?api-key=
```
Single-encoding (`Five%26Twenty%23Blackbirds`) would be decoded by the server before the router sees it, producing `Five&Twenty#Blackbirds` in the path, which breaks routing. So you need different encoding for resource addressing vs querying.
---
### 1. Discover the API Schema Before You Act
Before working with a resource you haven't used before, fetch its metadata. This tells you the field names, types, required fields, related resources, and available custom actions - so you don't guess.
**List all available resources:**
```
GET /Metadata.json?api-key=&$skip=0&$top=200
```
Returns an array of `{ Name, KeyProperty, EntityName }` - the full catalogue of resources. Also returns a `Build-Version` response header (e.g. `1.6.12497.2749`) - **record this value**.
> **Important:** `/Metadata.json` obeys the same 20-record default page size as every other list endpoint. Without `$top`, you will only see the first 20 resources alphabetically and silently miss the rest. Always supply `$top=200` (or page with `$skip` if you have more than 200 resources).
**Get full field and action detail for one resource:**
```
GET /Metadata/ResourceName.json?api-key=&$expand=Metadata
```
Returns field definitions (`Properties`), related resources (`NavigationProperties`), and custom actions (`QueryActions`).
Look for `"Nullable": false` to identify required fields before creating a record.
The metadata also includes a `WritableCollections` field - a dot-notated, comma-separated list of child navigation properties that can be written through this parent's PUT body (e.g. `"Items"` or `"Vessels.Additions"`). Items in a collection named here can be written through the parent entity; its own endpoint may not accept writes directly.
**Build-version caching:** Every API response includes a `build-version` header. Metadata is stable within a build version - cache it against that version string and reuse it without re-fetching for as long as the version stays the same. If the `build-version` changes mid-session, discard your cached metadata and re-fetch before proceeding.
---
### 2. Always Use $select
Every list or get request must include a `$select` parameter. Without it the API returns all fields, which creates large responses that waste time and context.
**Scalar fields only:**
```
GET /SalesOrders.json?api-key=&$select=SalesOrderNum,Status,InvoiceDate,ContactNum
```
**Include a related collection (all fields):**
```
GET /SalesOrders/8821.json?api-key=&$select=SalesOrderNum,Status,Items
```
**Include a related collection with filtering and field shaping (preferred):**
```
GET /SalesOrders/8821.json?api-key=
&$select=SalesOrderNum,Items/Select(new(StockItemCode,Quantity,UnitPrice)) as Items
GET /StockItems/345.json?api-key=
&$select=StockItemNum,Description,Prices/Where(IsActive eq true)/Select(new(Price,PriceDescription)) as Prices
GET /StockItems.json?api-key=
&$select=StockItemNum,Description,Prices/Where(IsActive eq true)/Select(new(Price,PriceDescription)) as Prices
```
Use the navigation property names from the `NavigationProperties` section of the resource metadata. Prefer inline projection over `$expand` - `$expand` returns full related collections with no filtering.
Omit `$select` only when you genuinely need every field.
---
### 3. Filter at the Source with $filter
Never fetch all records and filter in your own code. Use `$filter` in the query string so the server does the work. The API can have thousands of records per resource.
**String match:**
```
$filter=contains(LegalName,'Ciao')
$filter=startswith(StockItemCode,'CHARD')
```
**Exact value:**
```
$filter=Status eq 'OPEN'
$filter=IsActive eq true
```
**Date range:**
Use `datetime'...'` for `DateTime` properties (UTC) and `datetimeoffset'...'` for `DateTimeOffset` properties. The time portion and offset are optional.
```
$filter=InvoiceDate gt datetime'2026-01-01'
$filter=InvoiceDate ge datetime'2026-01-01T00:00:00' and InvoiceDate lt datetime'2026-02-01T00:00:00'
$filter=CreatedAt gt datetimeoffset'2026-01-01T00:00:00%2B13:00'
```
**Membership (like SQL IN):**
```
$filter=contains(new[2,3,5], SalesOrderNum)
```
**Compound:**
```
$filter=IsActive eq true and Type eq 'Customer'
```
**Filter on a related collection (lambda - avoids a second request):**
The parameter is implied - write the field name directly, no variable prefix.
```
$filter=Prices/Any(Price gt 6.0)
$filter=Tags/Any(Name eq 'Organic')
$filter=Items/All(Quantity gt 0)
$filter=Addresses/Any(Type eq 'Billing' and Country eq 'NZ')
```
**Operators:** `eq`, `ne`, `lt`, `le`, `gt`, `ge`, `and`, `or`, `not`
**String functions:** `contains()`, `startswith()`, `endswith()`
**String values:** always single-quoted. **Dates:** use `datetime'YYYY-MM-DD'` or `datetime'YYYY-MM-DDThh:mm:ss'` for `DateTime` fields; use `datetimeoffset'YYYY-MM-DDThh:mm:ss%2BHH:MM'` for `DateTimeOffset` fields (`+` must be URL-encoded as `%2B` - a bare `+` in a query string is interpreted as a space). DateTime is UTC; the time component and offset are optional.
---
### 4. Page Through Large Result Sets
The API returns 20 records by default. If you receive exactly `$top` records (or exactly 20 when `$top` is omitted), assume there are more pages.
**Paging rules:**
- Always set `$top` and `$orderby` explicitly when paging - this ensures stable page boundaries.
- Page sequence: `$skip=0` → `$skip=$top` → `$skip=$top*2` → ...
- Stop when a page returns fewer records than `$top`.
```
# Page 1
GET /Contacts.json?api-key=
&$filter=IsActive eq true
&$select=ContactNum,LegalName
&$orderby=LegalName asc
&$skip=0&$top=50
# Page 2 (only if page 1 returned exactly 50 records)
GET /Contacts.json?api-key=
&$filter=IsActive eq true
&$select=ContactNum,LegalName
&$orderby=LegalName asc
&$skip=50&$top=50
```
Don't fetch more pages than you need. If the user asked for the first 10 results, use `$top=10` and stop.
---
### 5. Self-Rate-Limit - Don't Hammer the API
The API enforces rate limits and returns HTTP 429 if called too rapidly. If you receive a 429, read the `Retry-After` response header and wait that many seconds before retrying. Do not retry in a tight loop.
To avoid hitting rate limits in the first place, please pre-emptively:
- **Don't wait for a 429, throttle your own calls
- **Don't loop over individual IDs.** Use `$filter=contains(new[1,2,3], KeyField)` to fetch multiple records in one call.
- **Cache metadata by build version.** The API returns a `Build-Version` header on every response. Metadata is stable within a build version - fetch it once, record the version, and reuse it for every subsequent step without re-fetching. If the `Build-Version` changes, re-fetch. Do not re-fetch the same endpoint's metadata on each tool call.
- **Don't repeat any call** if you already have the data from an earlier step in this session.
- **Combine work into fewer, richer calls.** Use inline `$select` projections to fetch related data in the same request rather than making a follow-up call.
---
### 6. OData Clause Order
The API applies query parameters in the order they appear in the URL. Always use this order:
```
$filter → $select → $orderby → $skip → $top
```
`$skip` must come before `$top` - if `$top` is applied first it truncates the result set before `$skip` can offset into it, so all pages after the first return zero records.
Full example URL:
```
GET /SalesOrders.json?api-key=
&$filter=Status eq 'OPEN'
&$select=SalesOrderNum,Status,InvoiceDate,ContactNum
&$orderby=InvoiceDate desc
&$skip=0
&$top=20
```
---
### 7. Creating Records - Check Required Fields First
Before POSTing a new record, fetch the resource metadata and identify which fields to include:
- **`"Nullable": false` and `"ReadOnly"` absent (or `false`)** - required, you must supply a value.
- **`"ReadOnly": true`** - server-managed; **omit entirely** from POST and PUT bodies. The server populates these automatically (running totals, computed quantities, timestamps). Including them has no effect and may cause an error.
```
# 1. Fetch field metadata
GET /Metadata/SalesOrders.json?api-key=&$expand=Metadata
→ include fields where Nullable is false AND ReadOnly is absent or false
→ skip any field where ReadOnly is true (e.g. UnitsInStock, TotalCost, datemodified)
# 2. Create the record - Content-Type: application/json
POST /SalesOrders.json?api-key=
Body: {
"ContactNum": 42,
"DivisionNum": 1,
"CurrencyNum": 1,
"InvoiceDate": "2026-03-13"
}
```
For PUT (update), send only the fields you want to change - not the full record - and again omit any `ReadOnly: true` fields.
For both PUT and POST you can specify a `$select` to reduce the size of the response.
---
### 8. Writing Child Collections Through the Parent
Some child-collection endpoints are **read-only on their own** - attempting to POST directly to them returns an error. Check the parent resource's `WritableCollections` metadata field before trying to write a child collection.
**How to check:**
```
GET /Metadata/SalesOrders.json?api-key=&$expand=Metadata
→ "WritableCollections": "Items"
```
`"Items"` present means line items must be written via the parent `SalesOrders` PUT, not directly to `SalesOrderItems`.
**Writing child records on initial creation - include them in the POST body:**
```
POST /SalesOrders.json?api-key=
Body: {
"ContactNum": 42,
"DivisionNum": 1,
"CurrencyNum": 1,
"InvoiceDate": "2026-03-13",
"Items": [
{ "StockItemNum": 117, "Quantity": 2, "UnitOfMeasureCode": "CASE" }
]
}
```
**Adding or updating child records on an existing parent - PUT to the parent with the collection in the body:**
```
PUT /SalesOrders/8821?api-key=
Body: {
"Items": [
{ "StockItemNum": 117, "Quantity": 2, "UnitOfMeasureCode": "CASE" }
]
}
```
**Nested writable collections** - dot notation in `WritableCollections` (e.g. `"Vessels.Additions"`) means `Additions` is a writable sub-collection within `Vessels`, and both levels can be nested in the PUT body.
If `WritableCollections` is empty or absent, the resource has no writable child collections - use the child endpoint's own POST/PUT directly.
---
### 9. Custom Actions
Some resources support actions beyond standard CRUD (e.g. sending an email, approving a document). The available actions are listed in the `QueryActions` array in the resource metadata.
Execute an action by appending `$action=ActionName` to the URL:
```
# Send an email from a sales order
POST /SalesOrders/8821.json?api-key=&$action=Email
Body: { "ToAddress": "customer@example.com" }
# Approve a purchase order
PUT /PurchaseOrders/4012.json?api-key=&$action=Approve
Body: { "ApprovalNotes": "Approved by manager" }
```
Check the action's `Parameters` list in the metadata for required fields before calling.
---
### 9. Request and Response Format
- Set `Content-Type: application/json` on POST and PUT requests.
- Set `Accept: application/json` on all requests.
- All responses are JSON. List endpoints return a JSON array; single-record endpoints return a JSON object.
- DELETE returns `{ "deleted": true }` on success.
---
### Quick Reference
```
# Discover resources
GET /Metadata.json?api-key=
# Understand one resource
GET /Metadata/SalesOrders.json?api-key=&$expand=Metadata
# Search
GET /SalesOrders.json?api-key=&$filter=Status eq 'OPEN'&$select=SalesOrderNum,Status&$orderby=InvoiceDate desc&$top=20
# Get one record
GET /SalesOrders/8821.json?api-key=&$select=SalesOrderNum,Status,Items
# Create
POST /SalesOrders.json?api-key= (JSON body)
# Update
PUT /SalesOrders/8821?api-key= (JSON body, changed fields only)
# Delete
DELETE /SalesOrders/8821?api-key=
# Custom action
POST /SalesOrders/8821.json?api-key=&$action=Email (JSON body)
```
---
### Example: End-to-End Workflow
**Task:** "Create a sales order for Ciao Restaurant for 2 cases of 25 Shiraz"
```
# 1. Find the contact
GET /Contacts.json?api-key=&$filter=contains(LegalName,'Ciao')&$select=ContactNum,LegalName
→ ContactNum: 42
# 2. Find the stock item
GET /StockItems.json?api-key=&$filter=contains(Description,'Shiraz')&$select=StockItemNum,Description,BaseUOM
→ StockItemNum: 117, BaseUOM: "CASE"
# 3. Check required fields for a new order
GET /Metadata/SalesOrders.json?api-key=&$expand=Metadata
→ Required: ContactNum, DivisionNum, CurrencyNum, InvoiceDate
# 4. Create the order
POST /SalesOrders.json?api-key=
Body: { "ContactNum": 42, "DivisionNum": 1, "CurrencyNum": 1, "InvoiceDate": "2026-03-13" }
→ SalesOrderNum: 8821
# 5. Check whether Items is writable via the parent
GET /Metadata/SalesOrders.json?api-key=&$expand=Metadata
→ WritableCollections: "Items" ← Items must be written through the parent, not via SalesOrderItems directly
# 6. Add the line item via a PUT to the parent order
PUT /SalesOrders/8821?api-key=
Body: { "Items": [{ "StockItemNum": 117, "Quantity": 2, "UnitOfMeasureCode": "CASE" }] }
```