> For the complete documentation index, see [llms.txt](https://t420.gitbook.io/t420/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://t420.gitbook.io/t420/api-mcp-spec.md).

# api-mcp-spec

## FleetOS API + MCP Integration Spec

### Objective

Make FleetOS usable by fleets **without requiring them to replace their current systems**.

FleetOS should become the **external service execution and communication layer** that sits between:

* fleet management platforms
* internal ERPs / work order systems
* external service suppliers
* WhatsApp / email / magic-link response flows
* future human and AI agents

The goal is not rip-and-replace. The goal is **interop-first adoption**.

***

### Product Positioning

#### FleetOS is not

* a full replacement for existing fleet systems
* a telematics platform
* a generic shop management clone
* just a marketplace

#### FleetOS is

* a cross-company service coordination layer
* a communication bridge between fleet and supplier
* a structured workflow engine for quote / approval / execution / completion
* a shared system of record for external service work
* an API-first and agent-ready workflow surface

***

### Integration Strategy

#### Phase 1

Build a **FleetOS REST API + webhooks**.

This allows existing fleet systems to:

* create work in FleetOS
* receive status updates back
* keep their current internal workflows and UIs

#### Phase 2

Build **communication adapters**:

* WhatsApp ingress
* email ingress
* magic-link actions
* attachment handling

#### Phase 3

Build an **MCP / agent tool layer**.

This allows:

* fleet-side agents
* supplier-side agents
* AI copilots
* orchestration tools

to interact with FleetOS through structured tools.

#### Phase 4

Build **native connectors** only after usage patterns are clear.

***

## Part 1 — Core Domain Model

### Primary Objects

#### 1. WorkOrder

Represents a fleet-originated or supplier-originated service job.

Suggested fields:

* `id`
* `external_id` — ID from external fleet/customer system
* `source_system`
* `source_type` — `fleet_api`, `manual`, `whatsapp`, `email`, `webform`, `agent`
* `fleet_company_id`
* `fleet_company_name`
* `supplier_company_id`
* `supplier_company_name`
* `fleet_contact_name`
* `fleet_contact_phone`
* `fleet_contact_email`
* `supplier_contact_name`
* `supplier_contact_phone`
* `supplier_contact_email`
* `vehicle_id`
* `vehicle_identifier`
* `vehicle_vin`
* `location`
* `fleet_company_address`
* `description`
* `service_category`
* `priority` — `emergency | urgent | routine`
* `commercial_status`
* `operational_status`
* `scheduled_start`
* `scheduled_end`
* `required_by`
* `budget_authorization_amount`
* `budget_authorization_currency`
* `quoted_amount`
* `quoted_currency`
* `final_cost_amount`
* `final_cost_currency`
* `assigned_technician_id`
* `assigned_technician_name`
* `bay_id`
* `bay_name`
* `vehicle_status`
* `tracking_token`
* `created_at`
* `updated_at`

#### 2. Quote

Represents supplier commercial response.

Suggested fields:

* `id`
* `work_order_id`
* `amount`
* `currency`
* `vat_type`
* `notes`
* `attachment_urls`
* `submitted_by_contact_id`
* `submitted_at`
* `approval_status`

#### 3. Assignment

Represents work execution ownership.

Suggested fields:

* `id`
* `work_order_id`
* `technician_id`
* `technician_name`
* `bay_id`
* `bay_name`
* `assigned_at`
* `assigned_by`

#### 4. PartRequirement

Suggested fields:

* `id`
* `work_order_id`
* `description`
* `status` — `none | in_stock | on_order | received`
* `eta`

#### 5. TimelineEvent

Used for audit trail.

Suggested fields:

* `id`
* `work_order_id`
* `event_type`
* `actor_type` — `fleet | supplier | system | agent`
* `actor_id`
* `actor_name`
* `payload`
* `created_at`

#### 6. Attachment

Suggested fields:

* `id`
* `work_order_id`
* `attachment_type` — `quote | invoice | completion_photo | request_photo | signature | misc`
* `url`
* `uploaded_by`
* `created_at`

***

## Part 2 — Suggested Status Model

### Commercial Status

* `requested`
* `quoted`
* `approved`
* `declined`
* `invoiced`

### Operational Status

* `unscheduled`
* `scheduled`
* `en_route`
* `in_progress`
* `waiting_parts`
* `ready_for_pickup`
* `completed`
* `cancelled`

### Priority

* `emergency`
* `urgent`
* `routine`

### Compatibility Rule

If the current DB still uses a single legacy status field, create a compatibility mapper. Do not expose the messy legacy model as the future API truth.

***

## Part 3 — REST API Surface

### Auth Model

Use API keys first.

#### Recommended auth modes

1. `X-API-Key` for server-to-server integration
2. OAuth later for native connector partners
3. signed magic-link tokens for human action flows

***

### 1. Create Work Order

`POST /api/v1/work-orders`

#### Purpose

Create an external service job in FleetOS from an existing fleet system.

#### Request body

```json
{
  "external_id": "WO-12345",
  "source_system": "fleetio",
  "fleet_company_id": "fleet_001",
  "fleet_company_name": "Acme Logistics",
  "supplier_company_id": "supplier_009",
  "supplier_company_name": "QuickFix Mobile Tires",
  "fleet_contact_name": "James Miller",
  "fleet_contact_phone": "+13055551234",
  "fleet_contact_email": "james@acme.com",
  "vehicle_identifier": "Truck #127",
  "vehicle_vin": "1FTFW1E50NFA00001",
  "location": "I-95 MM 42 Northbound",
  "description": "Front left tire blowout",
  "service_category": "tires",
  "priority": "emergency",
  "budget_authorization_amount": 600,
  "budget_authorization_currency": "USD",
  "required_by": "2026-04-05T18:00:00Z"
}
```

#### Response

```json
{
  "id": "wo_abc123",
  "tracking_token": "trk_xyz",
  "commercial_status": "requested",
  "operational_status": "unscheduled",
  "created_at": "2026-04-04T18:30:00Z"
}
```

***

### 2. Get Work Order

`GET /api/v1/work-orders/{id}`

#### Purpose

Retrieve current state for sync back into the fleet’s system.

#### Response includes

* core work order fields
* commercial status
* operational status
* quote data
* assignments
* parts
* attachments
* timeline summary

***

### 3. List Work Orders

`GET /api/v1/work-orders`

#### Suggested filters

* `external_id`
* `fleet_company_id`
* `supplier_company_id`
* `commercial_status`
* `operational_status`
* `priority`
* `updated_after`
* `vehicle_identifier`

***

### 4. Submit Quote

`POST /api/v1/work-orders/{id}/quote`

#### Purpose

Supplier submits a quote through UI, API, email adapter, WhatsApp adapter, or agent.

#### Request body

```json
{
  "amount": 450,
  "currency": "USD",
  "vat_type": "exclusive",
  "notes": "Includes mobile call-out and replacement tire",
  "attachment_urls": [
    "https://cdn.fleetos.us/quotes/q123.pdf"
  ]
}
```

#### Result

* commercial status becomes `quoted`
* webhook fires to fleet system

***

### 5. Approve Quote

`POST /api/v1/work-orders/{id}/approve-quote`

#### Purpose

Fleet approves quote while keeping its core system intact.

#### Request body

```json
{
  "approved_by": "fleet_user_01"
}
```

#### Result

* commercial status becomes `approved`
* operational status can remain `unscheduled` or move according to current workflow rules

***

### 6. Decline Quote

`POST /api/v1/work-orders/{id}/decline-quote`

#### Request body

```json
{
  "reason": "Above authorization limit"
}
```

***

### 7. Assign Resources

`POST /api/v1/work-orders/{id}/assign`

#### Purpose

Assign technician, bay, or other execution resources.

#### Request body

```json
{
  "technician_id": "tech_22",
  "technician_name": "Tony Reyes",
  "bay_id": "bay_4",
  "bay_name": "Bay 4",
  "scheduled_start": "2026-04-05T09:00:00Z",
  "scheduled_end": "2026-04-05T10:30:00Z"
}
```

***

### 8. Start Work

`POST /api/v1/work-orders/{id}/start`

#### Result

* operational status becomes `in_progress`
* timeline event created
* webhook emitted

***

### 9. Update Parts

`POST /api/v1/work-orders/{id}/parts` `PATCH /api/v1/work-orders/{id}/parts/{partId}`

#### Purpose

Track blocking parts status.

***

### 10. Mark Ready for Pickup

`POST /api/v1/work-orders/{id}/ready-for-pickup`

#### Request body

```json
{
  "notes": "Vehicle tested and ready"
}
```

***

### 11. Request Vehicle Delivery

`POST /api/v1/work-orders/{id}/request-delivery`

#### Request body

```json
{
  "delivery_date": "2026-04-05T15:00:00Z"
}
```

***

### 12. Complete Work

`POST /api/v1/work-orders/{id}/complete`

#### Request body

```json
{
  "final_cost_amount": 470,
  "final_cost_currency": "USD",
  "invoice_attachment_urls": ["https://cdn.fleetos.us/invoices/inv_99.pdf"],
  "completion_photo_urls": ["https://cdn.fleetos.us/photos/comp_11.jpg"],
  "signature_url": "https://cdn.fleetos.us/signatures/sig_01.png",
  "notes": "Job complete"
}
```

***

### 13. Cancel Work Order

`POST /api/v1/work-orders/{id}/cancel`

#### Request body

```json
{
  "reason": "Vehicle reassigned to another supplier"
}
```

***

### 14. Attachments

`POST /api/v1/work-orders/{id}/attachments`

#### Attachment types

* quote
* invoice
* completion\_photo
* request\_photo
* signature
* misc

***

## Part 4 — Webhook Surface

### Why webhooks matter

This is how fleets keep their current system but still stay synced with FleetOS.

### Webhook event examples

* `work_order.created`
* `quote.submitted`
* `quote.approved`
* `quote.declined`
* `assignment.updated`
* `work.started`
* `work.waiting_parts`
* `work.ready_for_pickup`
* `delivery.requested`
* `work.completed`
* `work.cancelled`

### Suggested webhook payload

```json
{
  "event": "quote.submitted",
  "timestamp": "2026-04-04T19:10:00Z",
  "data": {
    "work_order_id": "wo_abc123",
    "external_id": "WO-12345",
    "commercial_status": "quoted",
    "operational_status": "unscheduled",
    "quote": {
      "amount": 450,
      "currency": "USD"
    }
  }
}
```

### Webhook security

* HMAC signature header
* replay-protection timestamp
* retry with exponential backoff
* dead-letter queue later

***

## Part 5 — Communication Gateway

### Objective

Turn messy supplier/fleet communication into structured job actions.

### Channels

* WhatsApp
* email
* magic-link web pages
* web forms

### Example message → structured action

"Quote is $450 and we can do it at 9am"

becomes:

* quote amount: 450
* quote currency: USD
* scheduled\_start: 9am
* commercial\_status: quoted

### Gateway responsibilities

* identity resolution
* work order matching
* attachment ingestion
* action parsing
* structured write to FleetOS
* audit event creation

This is a key differentiator.

***

## Part 6 — MCP / Agent Layer

### Why MCP matters

The future workflow is not only human-to-human. It will increasingly be:

* human to agent
* agent to human
* agent to agent

FleetOS should expose safe, structured tools.

### Suggested MCP tools

#### 1. `create_work_order`

Create a new FleetOS work order.

#### 2. `get_work_order`

Retrieve current work order state.

#### 3. `list_work_orders`

Search work orders by filters.

#### 4. `submit_quote`

Submit or update a quote.

#### 5. `approve_quote`

Approve supplier quote.

#### 6. `decline_quote`

Decline supplier quote.

#### 7. `assign_resources`

Assign technician, bay, and schedule.

#### 8. `start_work`

Mark work as in progress.

#### 9. `update_part_status`

Update parts status and ETA.

#### 10. `mark_ready_for_pickup`

Signal vehicle ready.

#### 11. `request_vehicle_delivery`

Request vehicle handoff/delivery.

#### 12. `complete_work`

Mark job completed with commercial and evidence payload.

#### 13. `cancel_work_order`

Cancel job.

#### 14. `get_timeline`

Return audit-trail events.

***

### Example MCP schema concept

```json
{
  "name": "approve_quote",
  "description": "Approve a supplier quote for a FleetOS work order",
  "input_schema": {
    "type": "object",
    "properties": {
      "work_order_id": { "type": "string" },
      "approved_by": { "type": "string" }
    },
    "required": ["work_order_id", "approved_by"]
  }
}
```

***

## Part 7 — Adoption Strategy

### Best first customer pitch

"Keep your current fleet system. Use FleetOS to run the supplier communication and execution layer cleanly."

That is much easier to sell than: "Replace your fleet system with FleetOS."

### Early ideal use cases

* mobile tire networks
* roadside suppliers
* repair and maintenance coordination
* fleets with many external suppliers
* suppliers serving many fleets

### Why this is strong

Because the real pain is in the messy middle:

* request
* quote
* approve
* assign
* execute
* close

That workflow usually escapes the system of record. FleetOS should own that layer.

***

## Part 8 — Recommended Build Order

### Phase 1

Build:

* core REST API
* work order model
* quote/approval endpoints
* webhook engine

### Phase 2

Build:

* WhatsApp ingress
* email ingress
* magic-link response pages
* attachment pipeline

### Phase 3

Build:

* MCP server/tool layer
* safe role-based tool permissions

### Phase 4

Build:

* native connectors after repeated usage patterns are clear

***

## Part 9 — Definition of Success

The API/MCP layer is successful when:

* fleets can create work in FleetOS without changing core systems
* suppliers can respond through low-friction channels
* FleetOS can push state changes back to fleet systems
* the quote/approval/execution loop is structured and auditable
* agents can safely call FleetOS tools
* FleetOS becomes the coordination layer, not just another dashboard


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://t420.gitbook.io/t420/api-mcp-spec.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.