Developers

Build on Fretie.

A REST API for quotes, rates, inbox and customers. An email ingestion webhook for any system that can speak HTTP. A remote MCP server so Claude, ChatGPT, Cursor and Gemini can use Fretie directly. Everything is described in machine-readable form first.

OpenAPI spec Connect an AI assistant Quickstart

Works withClaudeChatGPTCursorGemini

Connect an AI assistant

The MCP server lives at https://mcp.fretie.com/mcp over Streamable HTTP. It requires OAuth 2.1: the first request gets a 401 with RFC 9728 discovery metadata, so a compliant client completes sign-in on its own and every session is scoped to the organisation the user belongs to.

Claude

Claude Code, Claude Desktop and claude.ai

In Claude Code, add the server from the terminal:

$ claude mcp add --transport http fretie https://mcp.fretie.com/mcp

In Claude Desktop or claude.ai, open Settings, then Connectors, choose Add custom connector and paste the URL. Sign in with your Fretie account when asked.

ChatGPT

Developer mode connectors

In ChatGPT open Settings, then Connectors, enable Developer mode and create a new connector with the MCP URL. Authentication is OAuth; ChatGPT redirects you to Fretie to sign in. Once connected, ask for rates or a draft quote in any conversation.

Cursor

Project or global MCP config

Add Fretie to .cursor/mcp.json in a project, or to the global file:

{
  "mcpServers": {
    "fretie": { "url": "https://mcp.fretie.com/mcp" }
  }
}

Cursor opens the sign-in flow the first time a tool is called.

Gemini

Gemini CLI

$ gemini mcp add --transport http fretie https://mcp.fretie.com/mcp

Other MCP clients work the same way: point them at the URL, complete OAuth, and the tools below appear.

Tools

Every tool runs as the signed-in user, inside that user's organisation, and appears in the audit log like any other agent run. Creating a quote spends one autopilot credit, the same as a quote from the inbox.

Tool	Scope	What it does
list_quotes	quotes:read	The organisation's quotes, most recent first, up to 50.
get_quote	quotes:read	One quote by reference, for example Q-2026-0001, with its charge lines and pricing provenance.
search_rates	rates:read	Search the rate ledger. Origin and destination match as substrings; every filter is optional.
create_quote_from_request	inbox:write	Turn a plain-language freight request into a draft quote: extract the request, match rates, apply margin rules, save the draft.
list_shipments	quotes:read	Shipments for the organisation, most recent first, up to 50.
get_reconciliation_summary	quotes:read	Quoted buy-side cost against actual carrier invoices across shipments, with counts and total leakage.
pipeline_snapshot	quotes:read	Quote count, total sell value and total margin per quote status.

REST API quickstart

Base URL https://api.fretie.com. JSON in, JSON out. Every operation has a unique operationId in the spec so function-calling agents can use it without a wrapper.

Get a token

Machine clients use the OAuth 2.0 client-credentials grant. Credentials are issued per organisation in the app under Settings, then Developers. Request only the scopes you need.

curl -X POST https://api.fretie.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"<your id>","client_secret":"<your secret>"}'

Call the API

Send the token as a bearer header. Tokens and API keys carry the same named scopes, so a request that lacks one fails with a 403 and the scope it needed.

curl https://api.fretie.com/quotes?limit=20 \
  -H "Authorization: Bearer <access_token>"

Push emails in

The ingestion webhook accepts raw emails from any system. Recognised quote requests run through the agent and come back as priced drafts in the inbox, with the same security screen as a connected mailbox.

curl -X POST https://api.fretie.com/ingest/email \
  -H "Authorization: Bearer <connector key>" \
  -H "Content-Type: application/json" \
  -d '{"from_email":"ops@customer.com","subject":"Rate needed, 2x40HC Shanghai to Rotterdam","body":"..."}'

Endpoints

The public surface today. Request and response schemas, parameters and error shapes are in the OpenAPI spec.

POST	/auth/token	Exchange client credentials for a bearer token.
GET	/quotes	List quotes. Cursor paginated.
GET	/quotes/{id}	One quote with charge lines, options and provenance.
GET	/rates	List rates in the ledger, with validity and surcharges.
GET	/rates/{id}	One rate.
GET	/inbox	Inbox messages and their agent runs.
POST	/inbox/{id}/generate	Run the quoting agent on a message and return the draft.
GET	/agent/runs/{id}	A single agent run with every step, result and timing.
GET	/customers	Customer records and tiers.
POST	/ingest/email	Push a raw email in from any system that can speak HTTP.
GET	/public/quotes/{id}	The customer-facing view of a sent quote (no auth).
POST	/public/quotes/{id}/accept	Customer accepts a sent quote (no auth).

Pagination

List endpoints take limit and starting_after and return a list envelope. Walk the pages by passing the last id back until has_more is false.

{
  "object": "list",
  "data": [ { "id": "q_01J...", "reference": "Q-2026-0139", ... } ],
  "has_more": true,
  "url": "/quotes"
}

Errors

Errors are plain JSON with a single machine-readable error field and a conventional status code.

401 Missing or invalid bearer token.
403 Token is valid but lacks the scope for this operation.
404 No such resource in your organisation.
402 The organisation has no credits for a metered action.
429 Too many requests in a short window. Back off and retry.

Every response is scoped to the organisation on the token. There is no way to address another organisation's data, by id or otherwise.

Authentication

Three ways in, all carrying the same named scopes.

OAuth 2.1 for people. The MCP server and any app acting on a user's behalf use the authorization-code flow with PKCE through WorkOS AuthKit. Metadata is published at the well-known URLs below.

Client credentials for services. A client id and secret issued per organisation, exchanged for a short-lived bearer token at /auth/token.

API keys for connectors. Long-lived keys issued per integration, scoped at creation and revocable at any time. The ingestion webhook uses a key with only ingest:write.

Scope	Grants
quotes:read	Read quotes and their provenance
quotes:write	Update quote status: approve, send, accept
rates:read	Read the rate ledger and surcharges
rates:write	Create and delete rates and surcharges
inbox:read	Read inbox messages and agent runs
inbox:write	Submit messages to the inbox and trigger quote generation
customers:read	Read customer records
customers:write	Create and delete customer records
ingest:write	Push raw emails into the ingestion endpoint

Getting data out

Automation webhooks

Automations in the app are trigger, condition, action chains, and one of the actions is an HTTP POST to a URL you own. Fire on a quote sent, a quote held under margin, an invoice variance or a stale rate, with the record in the body. A non-2xx response is recorded as a failed run in the automation's log.

TMS sync

Confirmed bookings are pushed to CargoWise and Magaya through the built-in connectors. For any other TMS, add an automation that posts accepted quotes to your endpoint and write the record yourself, or poll /quotes for status changes.

Exports

The rate ledger, quotes and reconciliation results export as CSV from the app at any time, and the same data is available through the API. Nothing is locked in.

Machine-readable resources

Everything a client or crawler needs to discover the API without reading this page.

OpenAPI spec

/openapi.json

Every public endpoint with operation ids, schemas and OAuth scopes.

Agent auth guide

/auth.md

How machine clients authenticate: OAuth 2.1 via WorkOS AuthKit, client-credentials tokens and API keys.

OAuth server metadata

/.well-known/oauth-authorization-server

RFC 8414 authorization-server metadata.

Protected resource metadata

/.well-known/oauth-protected-resource/mcp

RFC 9728 metadata the MCP server advertises on a 401.

API catalog

/.well-known/api-catalog

RFC 9727 linkset pointing at the API, its spec and the MCP server.

MCP server card

/.well-known/mcp/server-card.json

Connection details for the MCP server: Streamable HTTP plus OAuth.

llms.txt

/llms.txt

Site overview for agents, with a markdown link for every page.

Markdown for agents

Every page on fretie.com is also served as clean markdown. Send Accept: text/markdown to any URL, or append /md to a feature or blog page. Start from /llms.txt.

Versioning

The API is unversioned in the path. Fields are added, never removed or renamed, and a breaking change would ship under a new path with the old one kept running. The OpenAPI document carries the current version number.

Credentials and help

API keys and client credentials are issued per organisation inside the app under Settings, then Developers. Sign in at app.fretie.com. The 14-day trial includes full API and MCP access.

Integration questions go to contact@fretie.com. Reference the endpoint or tool name and we can usually answer the same day. If you are evaluating for a larger rollout, book a demo and bring your integration questions to the call.