{
  "openapi": "3.1.0",
  "info": {
    "title": "Open Drive Agent API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "/",
      "description": "Same origin as this document"
    },
    {
      "url": "https://opendrive.fun",
      "description": "Production"
    },
    {
      "url": "https://dev.opendrive.fun",
      "description": "Development"
    }
  ],
  "externalDocs": {
    "description": "Agent guide and MCP examples",
    "url": "/AGENTS.md"
  },
  "components": {
    "securitySchemes": {
      "AgentToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "odr_",
        "description": "Personal token created by a signed-in user at /agents. The required scope is listed on each action."
      }
    }
  },
  "paths": {
    "/api/agent/v1/actions": {
      "get": {
        "operationId": "list_agent_actions",
        "summary": "List the read-only actions",
        "responses": {
          "200": {
            "description": "Action registry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "version",
                    "actions"
                  ],
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "actions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "name",
                          "version",
                          "title",
                          "description",
                          "risk",
                          "scope",
                          "inputSchema",
                          "outputSchema",
                          "backingRoute"
                        ],
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "version": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "risk": {
                            "const": "read_only"
                          },
                          "scope": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "inputSchema": {
                            "type": "object"
                          },
                          "outputSchema": {
                            "type": "object"
                          },
                          "backingRoute": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid agent token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/actions/search_vehicles": {
      "post": {
        "operationId": "search_vehicles",
        "summary": "Find cars",
        "description": "Find available ride-hailing rentals by city, country, fuel, rental type or price. Weekly and slot prices use different time units. Demo listings are marked isDemo.",
        "x-backing-route": "GET /api/vehicles",
        "x-action-version": "1.0.0",
        "x-risk": "read_only",
        "x-required-scope": null,
        "security": [
          {},
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "additionalProperties": false,
                "properties": {
                  "input": {
                    "type": "object",
                    "properties": {
                      "city": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                      },
                      "country": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                      },
                      "fuel": {
                        "type": "string",
                        "enum": [
                          "Electric",
                          "Hybrid",
                          "Diesel",
                          "Petrol"
                        ]
                      },
                      "modality": {
                        "type": "string",
                        "enum": [
                          "weekly",
                          "slot"
                        ]
                      },
                      "max_price": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 5000
                      },
                      "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 50,
                        "default": 20
                      }
                    },
                    "additionalProperties": false
                  }
                }
              },
              "example": {
                "input": {
                  "limit": 3
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "vehicles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,32}$"
                          },
                          "brand": {
                            "type": "string"
                          },
                          "model": {
                            "type": "string"
                          },
                          "city": {
                            "type": "string"
                          },
                          "country": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "modality": {
                            "type": "string"
                          },
                          "pricePerWeek": {
                            "type": "number"
                          },
                          "deposit": {
                            "type": "number"
                          },
                          "slotPriceDay": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "slotPriceNight": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "imageUrl": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "rentalTerms": {
                            "type": [
                              "object",
                              "null"
                            ]
                          },
                          "isDemo": {
                            "type": "boolean"
                          },
                          "updatedAt": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "brand",
                          "model",
                          "city",
                          "country",
                          "currency",
                          "modality",
                          "pricePerWeek",
                          "deposit",
                          "slotPriceDay",
                          "slotPriceNight",
                          "imageUrl",
                          "rentalTerms",
                          "isDemo",
                          "updatedAt"
                        ]
                      },
                      "maxItems": 50
                    }
                  },
                  "required": [
                    "vehicles"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid agent token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope or disallowed origin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Requested record unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Expected application/json",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input does not match the schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/actions/get_vehicle": {
      "post": {
        "operationId": "get_vehicle",
        "summary": "Car details",
        "description": "Read one available listing by ID. Use an ID returned by Find cars. Contact details and registration plates are omitted.",
        "x-backing-route": "GET /api/vehicles/{id}",
        "x-action-version": "1.0.0",
        "x-risk": "read_only",
        "x-required-scope": null,
        "security": [
          {},
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "additionalProperties": false,
                "properties": {
                  "input": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9_-]{1,32}$"
                      }
                    },
                    "additionalProperties": false,
                    "required": [
                      "id"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "vehicle": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[A-Za-z0-9_-]{1,32}$"
                        },
                        "brand": {
                          "type": "string"
                        },
                        "model": {
                          "type": "string"
                        },
                        "city": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "modality": {
                          "type": "string"
                        },
                        "pricePerWeek": {
                          "type": "number"
                        },
                        "deposit": {
                          "type": "number"
                        },
                        "slotPriceDay": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "slotPriceNight": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "imageUrl": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "rentalTerms": {
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "isDemo": {
                          "type": "boolean"
                        },
                        "updatedAt": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "brand",
                        "model",
                        "city",
                        "country",
                        "currency",
                        "modality",
                        "pricePerWeek",
                        "deposit",
                        "slotPriceDay",
                        "slotPriceNight",
                        "imageUrl",
                        "rentalTerms",
                        "isDemo",
                        "updatedAt"
                      ]
                    }
                  },
                  "required": [
                    "vehicle"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid agent token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope or disallowed origin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Requested record unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Expected application/json",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input does not match the schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/actions/get_market_rates": {
      "post": {
        "operationId": "get_market_rates",
        "summary": "Market rates",
        "description": "Read reference earnings and operating costs by city. These are estimates.",
        "x-backing-route": "GET /api/market/rates",
        "x-action-version": "1.0.0",
        "x-risk": "read_only",
        "x-required-scope": null,
        "security": [
          {},
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "additionalProperties": false,
                "properties": {
                  "input": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": false
                  }
                }
              },
              "example": {
                "input": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "currency": {
                          "type": "string"
                        },
                        "weeksPerMonth": {
                          "type": "number"
                        },
                        "utilization": {
                          "type": "number"
                        },
                        "baseHoursWeek": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "currency",
                        "weeksPerMonth",
                        "utilization",
                        "baseHoursWeek"
                      ]
                    },
                    "cities": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "country": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "hourlyGross": {
                            "type": "number"
                          },
                          "evCostPerHour": {
                            "type": "number"
                          },
                          "hybridCostPerHour": {
                            "type": "number"
                          },
                          "fuelCostPerHour": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "country",
                          "currency",
                          "hourlyGross",
                          "evCostPerHour",
                          "hybridCostPerHour",
                          "fuelCostPerHour"
                        ]
                      }
                    }
                  },
                  "required": [
                    "meta",
                    "cities"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid agent token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope or disallowed origin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Requested record unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Expected application/json",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input does not match the schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/actions/compare_vehicle_costs": {
      "post": {
        "operationId": "compare_vehicle_costs",
        "summary": "Compare earnings",
        "description": "Rank available cars by estimated monthly driver earnings after rent and running costs, using the same filters as Find cars and the city market rates. A city without market rates returns no cars and emptyCity true. Cars without an estimate come last with estMonthlyReason. Values are estimates. Demo listings are marked isDemo.",
        "x-backing-route": "GET /api/vehicles + GET /api/market/rates",
        "x-action-version": "1.0.0",
        "x-risk": "read_only",
        "x-required-scope": null,
        "security": [
          {},
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "additionalProperties": false,
                "properties": {
                  "input": {
                    "type": "object",
                    "properties": {
                      "city": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                      },
                      "country": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 100
                      },
                      "fuel": {
                        "type": "string",
                        "enum": [
                          "Electric",
                          "Hybrid",
                          "Diesel",
                          "Petrol"
                        ]
                      },
                      "modality": {
                        "type": "string",
                        "enum": [
                          "weekly",
                          "slot"
                        ]
                      },
                      "max_price": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 5000
                      },
                      "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 50,
                        "default": 20
                      }
                    },
                    "additionalProperties": false
                  }
                }
              },
              "example": {
                "input": {
                  "city": "Lisbon",
                  "limit": 3
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "city": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "fuel": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "enum": [
                        "Electric",
                        "Hybrid",
                        "Diesel",
                        "Petrol",
                        null
                      ]
                    },
                    "market": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "hourlyGross": {
                          "type": "number"
                        },
                        "operatingCostPerHour": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "hoursPerWeek": {
                          "type": "number"
                        },
                        "weeksPerMonth": {
                          "type": "number"
                        },
                        "utilization": {
                          "type": "number"
                        },
                        "currency": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "hourlyGross",
                        "operatingCostPerHour",
                        "hoursPerWeek",
                        "weeksPerMonth",
                        "utilization",
                        "currency"
                      ]
                    },
                    "vehicles": {
                      "type": "array",
                      "maxItems": 50,
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,32}$"
                          },
                          "brand": {
                            "type": "string"
                          },
                          "model": {
                            "type": "string"
                          },
                          "city": {
                            "type": "string"
                          },
                          "fuel": {
                            "type": "string"
                          },
                          "pricePerWeek": {
                            "type": "number"
                          },
                          "deposit": {
                            "type": "number"
                          },
                          "estMonthly": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "estMonthlyReason": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "enum": [
                              "slot_pricing",
                              "no_market_rates",
                              "unsupported_fuel",
                              "not_estimated",
                              null
                            ]
                          },
                          "isDemo": {
                            "type": "boolean"
                          },
                          "netBreakdown": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "grossMonthly": {
                                "type": "number"
                              },
                              "operatingMonthly": {
                                "type": "number"
                              },
                              "rentMonthly": {
                                "type": "number"
                              },
                              "net": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "grossMonthly",
                              "operatingMonthly",
                              "rentMonthly",
                              "net"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "brand",
                          "model",
                          "city",
                          "fuel",
                          "pricePerWeek",
                          "deposit",
                          "estMonthly",
                          "estMonthlyReason",
                          "isDemo",
                          "netBreakdown"
                        ]
                      }
                    },
                    "emptyCity": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "city",
                    "fuel",
                    "market",
                    "vehicles",
                    "emptyCity"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid agent token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope or disallowed origin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Requested record unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Expected application/json",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input does not match the schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/actions/list_my_saved_vehicles": {
      "post": {
        "operationId": "list_my_saved_vehicles",
        "summary": "My saved cars",
        "description": "List the vehicle IDs saved by the token owner.",
        "x-backing-route": "GET /api/saved",
        "x-action-version": "1.0.0",
        "x-risk": "read_only",
        "x-required-scope": "saved:read",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "additionalProperties": false,
                "properties": {
                  "input": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "saved": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9_-]{1,32}$"
                      }
                    }
                  },
                  "required": [
                    "saved"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid agent token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope or disallowed origin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Requested record unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Expected application/json",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input does not match the schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/actions/list_my_rentals": {
      "post": {
        "operationId": "list_my_rentals",
        "summary": "My rentals",
        "description": "Read the token owner’s rental agreements and upcoming shift reminders.",
        "x-backing-route": "GET /api/rentals/mine",
        "x-action-version": "1.0.0",
        "x-risk": "read_only",
        "x-required-scope": "rentals:read",
        "security": [
          {
            "AgentToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "additionalProperties": false,
                "properties": {
                  "input": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Read result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rentals": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "vehicle_id": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,32}$"
                          },
                          "brand": {
                            "type": "string"
                          },
                          "model": {
                            "type": "string"
                          },
                          "starts_on": {
                            "type": "string"
                          },
                          "ends_on": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "vehicle_id",
                          "brand",
                          "model",
                          "starts_on",
                          "ends_on"
                        ]
                      },
                      "maxItems": 100
                    },
                    "reminders": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "due": {
                            "type": "string"
                          },
                          "brand": {
                            "type": "string"
                          },
                          "model": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "start",
                              "handover"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "due",
                          "brand",
                          "model",
                          "kind"
                        ]
                      },
                      "maxItems": 200
                    }
                  },
                  "required": [
                    "rentals",
                    "reminders"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid agent token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope or disallowed origin",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Requested record unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Expected application/json",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Input does not match the schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "requestId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  }
}
