API Endpoints

FerryGate exposes two API protocols: REST API (traditional HTTP endpoints) and MCP (Model Context Protocol for AI agents). Both use the same Bearer token authentication and connect to the same 35+ ferry operators.

REST API

Authentication

You'll need to include an access token in every request you make to the API.

To create an access token, head to your Dashboard. When you create an access token, you'll be able to choose whether to give it read-only or read-write access.

Send your access token in the Authorization request header using the "Bearer" authentication scheme:

Shell

Authorization: Bearer <YOUR_ACCESS_TOKEN>

Versioning

You can optionally send a x-client-version header with each request to specify which version of the API you want to use.

Shell

x-client-version: 2

Note:

The x-client-version header is accepted for backward compatibility but is no longer required. All requests use the latest API version automatically.

MIME types

All responses from the API are in JSON format with UTF-8 encoding. An Accept header is required with every request:

Shell

Accept: application/json

All request bodies sent to the API should be in JSON format. A Content-Type header is required whenever you're sending a request body (i.e. for POST and PUT requests):

Shell

Content-Type: application/json

Compression

We recommend enabling compression for responses returned by the API, since they can be very large. To enable compression, send an Accept-Encoding header:

Shell

Accept-Encoding: gzip

You'll need to configure your HTTP client to decompress responses. Most clients will have this functionality built-in.

Request ID

All responses will contain an x-request-id header. The value in this header uniquely identifies the request/response.

Shell

x-request-id: 5e58ca8b-51eb-4e7c-88bc-32e2bb227b14

We recommend you keep track of this header for debugging purposes. When interacting with the Ferrygate API support team providing this header will allow the team to give you prompt and personalised support.

Client Correlation ID

Sometimes, you may want to send your own ID in the headers so that you can correlate requests and responses sent from Ferrygate.

We also provide a header named x-client-correlation-id for that purpose.

All responses will contain an x-client-correlation-id header. The value in this header allows you to set your own client identifier per request/response.

Shell

x-client-correlation-id: Fs1ffv5QZAgVh6kATEST

When your API client does not set this header, it will have the same value as x-request-id in the response.

Language Support

You can specify your preferred language for API responses by sending an Accept-Language header. This affects localized content such as error messages and location names.

Shell

Accept-Language: fr

Complete Request Example

Here's a complete example showing all required headers in a typical API request for checking ferry availability.

This example demonstrates:

All authentication and versioning headers
Request structure with outbound journey details
Passenger information (adult, 25 years old)
Vehicle details (Peugeot 208)
One-way trip configuration

About this example:

Route: Sete (SET) to Tangier Med (TGM)
Company: Grandi Navi Veloci
Date: December 28, 2025 at 19:00
Trip type: One-way (outbound only)

Round-trip bookings: To create a round-trip booking, populate the ret_journey_id, ret_at, and ret_time fields with return journey details.

Code Examples

curl --location 'https://api.ferrygate.com/api/availability' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-client-correlation-id: Fs1ffv5QZAgVh6kATEST' \
  --header 'Accept-Language: fr' \
  --header 'x-client-version: 2' \
  --header 'Authorization: Bearer YOUR_API_TOKEN_HERE' \
  --data '{
    "request": {
        "company": "grandinaviveloci",
        "depart_code": "SET",
        "arrive_code": "TGM",
        "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
        "out_at": "2025-12-28",
        "out_time": "19:00",
        "out_is_open": false,
        "ret_journey_id": "",
        "ret_at": "",
        "ret_time": "",
        "ret_is_open": false
    },
    "passengers": [
        {
            "order": 1,
            "type": "Adult",
            "param": "A",
            "gender": "Male",
            "age": 25
        }
    ],
    "vehicle": {
        "code": "PEUGEOT__208"
    }
}'

const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("x-client-correlation-id", "Fs1ffv5QZAgVh6kATEST");
myHeaders.append("Accept-Language", "fr");
myHeaders.append("x-client-version", "2");
myHeaders.append("Authorization", "Bearer YOUR_API_TOKEN_HERE");

const raw = JSON.stringify({
  "request": {
    "company": "grandinaviveloci",
    "depart_code": "SET",
    "arrive_code": "TGM",
    "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
    "out_at": "2025-12-28",
    "out_time": "19:00",
    "out_is_open": false,
    "ret_journey_id": "",
    "ret_at": "",
    "ret_time": "",
    "ret_is_open": false
  },
  "passengers": [
    {
      "order": 1,
      "type": "Adult",
      "param": "A",
      "gender": "Male",
      "age": 25
    }
  ],
  "vehicle": {
    "code": "PEUGEOT__208"
  }
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://api.ferrygate.com/api/availability", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.ferrygate.com/api/availability',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "request": {
        "company": "grandinaviveloci",
        "depart_code": "SET",
        "arrive_code": "TGM",
        "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
        "out_at": "2025-12-28",
        "out_time": "19:00",
        "out_is_open": false,
        "ret_journey_id": "",
        "ret_at": "",
        "ret_time": "",
        "ret_is_open": false
    },
    "passengers": [
        {
            "order": 1,
            "type": "Adult",
            "param": "A",
            "gender": "Male",
            "age": 25
        }
    ],
    "vehicle": {
        "code": "PEUGEOT__208"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Content-Type: application/json',
    'x-client-correlation-id: Fs1ffv5QZAgVh6kATEST',
    'Accept-Language: fr',
    'x-client-version: 2',
    'Authorization: Bearer YOUR_API_TOKEN_HERE'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Security Best Practices

Keep your API token secure and never expose it in client-side code or public repositories
Rotate your tokens regularly and immediately if compromised
Use environment variables to store tokens in your application
Use read-only tokens when write access is not required

Booking Flow

Search Availability

POST/api/availability

Description

Search for available ferry sailings based on routes, dates, passengers, and optional vehicle information. This is the first step in the booking flow. The endpoint returns a list of available sailings with pricing, accommodation options (cabins, seats), meal options, and sailing details including departure/arrival times, ferry company information, and ship names.

Request Parameters

Parameter	Type	Required	Description
request (object)
company	string	Yes	Ferry company identifier
depart_code	string	Yes	Departure port code
arrive_code	string	Yes	Arrival port code
out_journey_id	string	Yes	Outbound journey UUID
out_at	string	Yes	Departure date (YYYY-MM-DD)
out_time	string	Yes	Departure time (HH:MM)
out_is_open	boolean	No	Open ticket (flexible date)
ret_journey_id	string	No	Return journey UUID
ret_at	string	No	Return date (YYYY-MM-DD)
ret_time	string	No	Return time (HH:MM)
ret_is_open	boolean	No	Return open ticket
passengers (array)
order	integer	Yes	Passenger order number
type	string	Yes	Adult, Child, Infant
param	string	Yes	Parameter code (A, C, I)
gender	string	Yes	Male, Female
age	integer	Yes	Passenger age
vehicle (object) - Optional
code	string	Yes	Vehicle code (BRAND__MODEL)

Response Fields

Field	Type	Description
id	string	Unique availability identifier
group_id	integer	Availability group number
direction	string	Outward or Return
journey_id	string	Journey UUID
sailing_id	string	Sailing identifier
depart_name	string	Departure port name
arrive_name	string	Arrival port name
depart_at	string	Departure datetime (ISO 8601)
arrive_at	string	Arrival datetime (ISO 8601)
company	object	Ferry company details
tariffs	array	Pricing options (Ticket, Presale, Option)
places	array	Accommodation options (Seat, Cabin, Suite)
ship_name	string	Name of the ferry
duration	integer	Journey duration in hours
stops	array	Intermediate port codes

Code Examples

Request

curl --location 'https://api.ferrygate.com/api/availability' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN_HERE' \
  --data '{
    "request": {
        "company": "grandinaviveloci",
        "depart_code": "SET",
        "arrive_code": "TGM",
        "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
        "out_at": "2025-12-28",
        "out_time": "19:00",
        "out_is_open": false,
        "ret_journey_id": "",
        "ret_at": "",
        "ret_time": "",
        "ret_is_open": false
    },
    "passengers": [
        {
            "order": 1,
            "type": "Adult",
            "param": "A",
            "gender": "Male",
            "age": 25
        }
    ],
    "vehicle": {
        "code": "PEUGEOT__208"
    }
}'

const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer YOUR_API_TOKEN_HERE");

const raw = JSON.stringify({
  "request": {
    "company": "grandinaviveloci",
    "depart_code": "SET",
    "arrive_code": "TGM",
    "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
    "out_at": "2025-12-28",
    "out_time": "19:00",
    "out_is_open": false,
    "ret_journey_id": "",
    "ret_at": "",
    "ret_time": "",
    "ret_is_open": false
  },
  "passengers": [
    {
      "order": 1,
      "type": "Adult",
      "param": "A",
      "gender": "Male",
      "age": 25
    }
  ],
  "vehicle": {
    "code": "PEUGEOT__208"
  }
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://api.ferrygate.com/api/availability", requestOptions)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.ferrygate.com/api/availability',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "request": {
        "company": "grandinaviveloci",
        "depart_code": "SET",
        "arrive_code": "TGM",
        "out_journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
        "out_at": "2025-12-28",
        "out_time": "19:00",
        "out_is_open": false,
        "ret_journey_id": "",
        "ret_at": "",
        "ret_time": "",
        "ret_is_open": false
    },
    "passengers": [
        {
            "order": 1,
            "type": "Adult",
            "param": "A",
            "gender": "Male",
            "age": 25
        }
    ],
    "vehicle": {
        "code": "PEUGEOT__208"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_API_TOKEN_HERE'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response (200 OK)

JSON - Array of availability objects

[
  {
    "id": "5e58ca8b-51eb-4e7c-88bc-32e2bb227b14#8e49e3...",
    "group_id": 1,
    "direction": "Outward",
    "journey_id": "1e5c463b-2e0a-45d1-be51-a2acab6d16fb",
    "sailing_id": "41640",
    "depart_name": "SETE",
    "depart_code": "SET",
    "arrive_name": "TANGER MED",
    "arrive_code": "TGM",
    "is_open": false,
    "depart_at": "2025-12-28T19:00:00+00:00",
    "arrive_at": "2025-12-30T18:45:00+00:00",
    "company": {
      "id": "21588986-ebd0-4339-ad7e-e60f7529d513",
      "name": "grandinaviveloci",
      "logo": "https://res.cloudinary.com/..."
    },
    "provider": {
      "id": "4cf00c5c-0411-40b4-8aa0-0faa0aea7ba4",
      "name": "grandinaviveloci"
    },
    "gateway": {
      "id": "966f4747-640a-492a-91f2-15714a380080",
      "code": "P999",
      "provider": "grandinaviveloci"
    },
    "tariffs": [
      {
        "id": "68e596c744a0c",
        "type": "Ticket",
        "amount": 84,
        "balance_amount": 0,
        "currency": "Eur",
        "date": 1759876807,
        "expiration_date": 1759878007
      },
      {
        "id": "68e596c744a1e",
        "type": "Presale",
        "amount": 50,
        "balance_amount": 34,
        "currency": "Eur",
        "expiration_date": 1764369607,
        "date": 1759876807
      },
      {
        "id": "68e596c744a26",
        "type": "Option",
        "amount": 0,
        "balance_amount": 84,
        "currency": "Eur",
        "date": 1759876807,
        "expiration_date": 1760049607
      }
    ],
    "places": [
      {
        "id": "68e596c7449ee",
        "index": 1,
        "code": "POL",
        "count": 1,
        "type": "Seat",
        "gender": "Any",
        "capacity": 1,
        "use": "Exclusive",
        "name": "Fauteuil",
        "in_board": {
          "adults": 1,
          "childs": 0,
          "babies": 0,
          "has_shower": true,
          "has_toilet": true,
          "has_window": true,
          "passengers": [...]
        }
      }
    ],
    "passenger_count": 1,
    "vehicle": [],
    "meals": [],
    "animals": null,
    "stops": ["BCN"],
    "ship_name": "Excellent",
    "duration": 47
  },
  // ... more availability options
]

Create Booking

POST/api/booking

Description

Create a new ferry booking with passenger details, selected availability, and optional vehicle information. This endpoint creates a reservation and returns a booking ID that can be used to confirm the booking. The booking will be in a pending state until confirmed.

Input Data

Parameter	Type	Required
availabilities	array	Yes
passengers	array	Yes
reservation_type	string	No
vehicle	object	No

Output Data

Field	Type	Description
booking_id	string	Booking ID
booking_reference	string	Reference
status	string	Status
total_price	number	Total price

Coding Sample

curl -X POST "https://api.ferrygate.com/api/booking" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "reservation_type": "TICKET",
    "availabilities": [
      {
        "availability_id": "AVL123456",
        "tariff_id": "TRF001",
        "place_id": "PLC123"
      }
    ],
    "passengers": [
      {
        "order": 1,
        "type": "Adult",
        "first_name": "John",
        "last_name": "Doe",
        "age": 30,
        "gender": "M",
        "email": "john.doe@example.com"
      }
    ]
  }'

# Response (201 Created)
{
  "booking_id": "BKG789012",
  "booking_reference": "FG-2025-789012",
  "status": "pending",
  "total_price": 145.50,
  "currency": "EUR"
}

Confirm Booking

POST/api/booking/confirm

Description

Confirm and finalize a ferry booking. This step locks in the reservation, processes payment, and generates tickets. Once confirmed, the booking cannot be modified without cancellation fees.

Input Data

Parameter	Type	Required
id	string	Yes

Output Data

Field	Type	Description
booking_id	string	Booking ID
status	string	Status (confirmed)
ticket_id	string	Ticket ID
ticket_number	string	Ticket reference

Coding Sample

curl -X POST "https://api.ferrygate.com/api/booking/confirm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{"id": "BKG789012"}'

# Response (201 Created)
{
  "booking_id": "BKG789012",
  "status": "confirmed",
  "ticket_id": "TKT345678",
  "ticket_number": "FG-TKT-345678"
}

Get Booking Details

GET/api/booking/{'{'}id{'}'}

Description

Retrieve complete details of an existing booking including passenger information, journey details, pricing, and current status. Use this endpoint to check booking status or retrieve booking information.

Input Data

Parameter	Type	Required
id	string	Yes

Output Data

Field	Type	Description
booking_id	string	Booking ID
booking_reference	string	Reference
status	string	Booking status
passengers	array	Passengers
journey_details	object	Journey info

Coding Sample

curl -X GET "https://api.ferrygate.com/api/booking/BKG789012" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "booking_id": "BKG789012",
  "booking_reference": "FG-2025-789012",
  "status": "confirmed",
  "passengers": [...],
  "journey_details": {...}
}

Cancel Booking

POST/api/booking/cancel

Description

Cancel an existing ferry booking. Cancellation policies and refund eligibility vary depending on the ferry operator and fare rules. Check the booking terms before cancellation.

Input Data

Parameter	Type	Required
booking_id	string	Yes
booking_reference	string	No

Output Data

Field	Type	Description
booking_id	string	Booking ID
status	string	Status (cancelled)
refund_amount	number	Refund amount

Coding Sample

curl -X POST "https://api.ferrygate.com/api/booking/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "booking_id": "BKG789012",
    "booking_reference": "FG-2025-789012"
  }'

# Response (201 Created)
{
  "booking_id": "BKG789012",
  "status": "cancelled",
  "refund_amount": 145.50
}

Get Ticket Details

GET/api/ticket/{'{'}id{'}'}

Description

Retrieve ferry ticket information including QR code, boarding details, and passenger information. Use this endpoint to display or download tickets for confirmed bookings.

Input Data

Parameter	Type	Required
id	string	Yes

Output Data

Field	Type	Description
ticket_id	string	Ticket ID
ticket_number	string	Ticket reference
qr_code	string	QR code (base64)
boarding_time	string	Boarding time

Coding Sample

curl -X GET "https://api.ferrygate.com/api/ticket/TKT345678" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "ticket_id": "TKT345678",
  "ticket_number": "FG-TKT-345678",
  "qr_code": "data:image/png;base64,...",
  "boarding_time": "2025-12-25T13:30:00+00:00"
}

Cancel Ticket

POST/api/ticket/cancel

Description

Cancel a ferry ticket. This action may incur cancellation fees depending on the fare rules and timing. Tickets must be cancelled before the departure time.

Input Data

Parameter	Type	Required
ticket_id	string	Yes
ticket_number	string	No

Output Data

Field	Type	Description
ticket_id	string	Ticket ID
status	string	Status (cancelled)

Coding Sample

curl -X POST "https://api.ferrygate.com/api/ticket/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "ticket_id": "TKT345678",
    "ticket_number": "FG-TKT-345678"
  }'

# Response (201 Created)
{
  "ticket_id": "TKT345678",
  "status": "cancelled"
}

Cancel Fee Preview

POST/api/booking/cancel-fee

Description

Preview the cancellation penalty and refund for a ticket without making any change. Read-only — use it to show the customer the cost before they confirm a cancellation.

Input Data

Parameter	Type	Required
id	string	Yes

Ticket or booking ID.

Output Data

Field	Type	Description
penalty_amount	number	Penalty charged on cancellation
refund_amount	number	Amount refunded to the customer
currency	string	Currency of the amounts
ticket_status	string	Current ticket status

Coding Sample

curl -X POST "https://api.ferrygate.com/api/booking/cancel-fee" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{"id": "TKT345678"}'

# Response (200 OK)
{
  "penalty_amount": 25.0,
  "refund_amount": 75.0,
  "currency": "EUR",
  "ticket_status": "Issued"
}

Ticket PDF

GET/api/ticket/{id}/pdf

Description

Retrieve the boarding voucher PDF for an issued ticket. Returns the document URL once it has been generated. Some carriers deliver the voucher by email instead — in that case url is null.

Input Data

Parameter	Type	Required
id	string	Yes

Ticket ID, passed in the URL path.

Output Data

Field	Type	Description
url	string \| null	PDF voucher URL, or null if not available yet

Coding Sample

curl -X GET "https://api.ferrygate.com/api/ticket/TKT345678/pdf" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "url": "https://res.cloudinary.com/ferrygate/.../GN-5746472.pdf"
}

Mark Ticket Paid

POST/api/ticket/{id}/mark-paid

Description

Mark a ticket as paid after collecting payment outside FerryGate (for example the B2C widget checkout on the merchant's own payment provider). Server-to-server only, authenticated with the organisation API token. Records the settlement so the ticket can then be issued.

Input Data

Parameter	Type	Required
id	string	Yes
external_payment_ref	string	Yes
psp	string	No
paid_at	string	No

id is the ticket ID (URL path). external_payment_ref is your PSP transaction reference; psp is the provider name; paid_at is an ISO 8601 timestamp.

Output Data

Field	Type	Description
ticket_id	string	Ticket ID
payment_status	string	Payment status (paid)

Coding Sample

Server-to-server only: call this from your backend with your organisation API token, never from a browser or the widget.

curl -X POST "https://api.ferrygate.com/api/ticket/TKT345678/mark-paid" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{"external_payment_ref": "pi_3Nxyz", "psp": "stripe"}'

# Response (200 OK)
{
  "ticket_id": "TKT345678",
  "payment_status": "paid"
}

Common Endpoints

Check Departures

POST/api/departure

Description

Get information about ferry departures for specific providers and journeys. Returns departure times and available dates for the requested routes.

Input Data

Parameter	Type	Required
provider_id	string	Yes
__journey_id	array	No

Output Data

Field	Type	Description
departures	array	Departures list
departure_times	array	Departure times

Coding Sample

curl -X POST "https://api.ferrygate.com/api/departure" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "provider_id": "DFDS",
    "__journey_id": ["JRN001"]
  }'

# Response (201 Created)
{
  "departures": [
    {
      "journey_id": "JRN001",
      "departure_times": ["14:30", "18:00"]
    }
  ]
}

Check Journeys

POST/api/journey

Description

Get information about available ferry journeys and routes including duration and provider details.

Input Data

No required parameters. Returns all available journeys.

Output Data

Field	Type	Description
journeys	array	Journey list
journey_id	string	Journey ID
route	string	Route

Coding Sample

curl -X POST "https://api.ferrygate.com/api/journey" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (201 Created)
{
  "journeys": [
    {
      "journey_id": "JRN001",
      "route": "Marseille - Dover",
      "duration_minutes": 480
    }
  ]
}

Check Ports

GET/api/port

Description

Get information about ferry ports including codes, locations, and facilities. Useful for building port selection interfaces.

Input Data

No required parameters. Returns all available ports.

Output Data

Field	Type	Description
ports	array	Ports list
code	string	Port code
name	string	Port name
country	string	Country

Coding Sample

curl -X GET "https://api.ferrygate.com/api/port" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "ports": [
    {
      "code": "FRMAR",
      "name": "Marseille",
      "country": "France"
    }
  ]
}

Vehicle Brands

GET/api/vehicle-brand

Description

Get a list of available vehicle brands for ferry transportation. Useful for vehicle selection forms.

Input Data

No required parameters. Returns all available vehicle brands.

Output Data

Field	Type	Description
brands	array	Brands list
id	string	Brand ID
name	string	Brand name

Coding Sample

curl -X GET "https://api.ferrygate.com/api/vehicle-brand" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "brands": [
    {"id": "1", "name": "Peugeot"},
    {"id": "2", "name": "Renault"}
  ]
}

Vehicle Data

GET/api/vehicle-data

Description

Get detailed vehicle data including types, dimensions, and specifications for ferry booking. Returns vehicle categories and their size restrictions.

Input Data

No required parameters. Returns all vehicle type information.

Output Data

Field	Type	Description
vehicle_types	array	Vehicle types
code	string	Type code
max_length	number	Max length (m)
max_height	number	Max height (m)

Coding Sample

curl -X GET "https://api.ferrygate.com/api/vehicle-data" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

# Response (200 OK)
{
  "vehicle_types": [
    {
      "code": "CAR",
      "name": "Car",
      "max_length": 5.0,
      "max_height": 2.0
    },
    {
      "code": "CAMPER",
      "name": "Camper Van",
      "max_length": 7.0,
      "max_height": 3.0
    }
  ]
}

MCP Protocol

Model Context Protocol (MCP)

MCP is an open standard by Anthropic that allows AI assistants (Claude, ChatGPT, custom agents) to interact with external tools and data. FerryGate exposes its full booking flow via MCP through a single endpoint.

MCP Endpoint

POST https://api.ferrygate.com/mcp
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>

How it works:

Protocol: JSON-RPC 2.0 over HTTP
Session: File-based, 1 hour TTL
Auth: Same Bearer API key as REST endpoints
Discovery: AI agents auto-discover available tools and resources

MCP Resources

Resources are read-only data catalogues that AI agents can query to discover ports, companies, vehicles and departures. Use resources/read to fetch them.

Ferry-Ports

RESresource://ferrygate/ports

All available ferry ports with codes, cities and GPS coordinates. Use this to discover port codes needed for availability search.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/ports"
  },
  "id": 1
}

Ferry-Companies

RESresource://ferrygate/companies

All ferry companies (Balearia, GNV, Armas, Meridionale) with logos and codes.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/companies"
  },
  "id": 1
}

Countries

RESresource://ferrygate/countries

All countries with ISO codes, phone prefixes and localized names.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/countries"
  },
  "id": 1
}

Vehicle-Brands

RESresource://ferrygate/vehicle-brands

All vehicle brands available for ferry bookings.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/vehicle-brands"
  },
  "id": 1
}

Vehicle-Data

RESresource://ferrygate/vehicle-data

Vehicle catalog with dimensions (height, length), brand and type.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/vehicle-data"
  },
  "id": 1
}

Departures

RESresource://ferrygate/departures

All scheduled ferry departures with journey, company, ports and ship information.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "resource://ferrygate/departures"
  },
  "id": 1
}

MCP Tools

Tools are actions that AI agents can call to execute the booking flow. Use tools/call with the tool name and arguments. The JSON body format is identical to the REST API.

search_availability

TOOLsearch_availability

Search available ferry sailings between two ports. Same input as POST /api/availability.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_availability",
    "arguments": {
      "request": {
        "company": "grandinaviveloci",
        "depart_code": "SET",
        "arrive_code": "TGM",
        "out_journey_id": "uuid",
        "out_at": "2026-07-15",
        "out_time": "19:00",
        "out_is_open": false,
        "ret_journey_id": "",
        "ret_at": "",
        "ret_time": "",
        "ret_is_open": false
      },
      "passengers": [
        { "order": 1, "type": "Adult", "param": "A", "gender": "Male", "age": 25 }
      ],
      "vehicle": { "code": "PEUGEOT__208" }
    }
  },
  "id": 1
}

create_booking

TOOLcreate_booking

Create a booking from a ticket ID obtained via search_availability. Same input as POST /api/booking.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_booking",
    "arguments": {
      "id": "ticket-uuid-from-availability",
      "reservation_type": "TICKET",
      "passengers": [
        { "order": 1, "type": "ADT", "gender": "M", "age": 30,
          "first_name": "John", "last_name": "Doe" }
      ],
      "contact": { "prefix": "+33", "phone": "612345678",
                   "name": "John Doe", "email": "john@example.com" }
    }
  },
  "id": 2
}

confirm_booking

TOOLconfirm_booking

Confirm a PRESALE/OPTION booking into a confirmed ticket. Same input as POST /api/booking/confirm.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "confirm_booking",
    "arguments": {
      "id": "ticket-uuid"
    }
  },
  "id": 3
}

view_ticket

TOOLview_ticket

Get ticket details including booking info, passengers, status and PDF data. Same as GET /api/ticket/{id}.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "view_ticket",
    "arguments": {
      "id": "ticket-uuid"
    }
  },
  "id": 4
}

cancel_ticket

TOOLcancel_ticket

Cancel a confirmed ticket. Same input as POST /api/ticket/cancel.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "cancel_ticket",
    "arguments": {
      "ticket_id": "ticket-uuid",
      "ticket_number": "BOOKING-REF-123"
    }
  },
  "id": 5
}

MCP Error Handling

When a tool call fails, the response contains a structured error object:

Error Response

{
  "error": true,
  "code": "AVAILABILITY_ERROR",
  "message": "No sailings found for the requested date"
}

Error Code	Tool
AVAILABILITY_ERROR	search_availability
BOOKING_CREATE_ERROR	create_booking
BOOKING_CONFIRM_ERROR	confirm_booking
TICKET_VIEW_ERROR	view_ticket
TICKET_NOT_FOUND	view_ticket
TICKET_CANCEL_ERROR	cancel_ticket