{
  "openapi": "3.1.0",
  "info": {
    "title": "STRELA Rent Agent API",
    "version": "1.0.0",
    "description": "Search construction-machinery rentals in Kazakhstan and send booking requests to owners on behalf of a signed-in client. The owner accepts or declines every request; requests are labelled as AI-created. Agents never pay: prepayment is made by the client via a link. Same capabilities are available over MCP at https://strela.top/mcp."
  },
  "servers": [
    {
      "url": "https://strela.top/api/agent/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://strela.top/oauth/authorize",
            "tokenUrl": "https://strela.top/oauth/token",
            "scopes": {
              "catalog:read": "Search listings",
              "orders:create": "Send and cancel booking requests on behalf of the client",
              "orders:read": "Read status of the client's booking requests"
            }
          }
        }
      },
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Personal access token created at https://strela.top/agent-access"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        }
      },
      "BookingInput": {
        "type": "object",
        "required": [
          "ref",
          "start_date",
          "end_date",
          "address"
        ],
        "properties": {
          "ref": {
            "type": "string",
            "example": "rent-123"
          },
          "start_date": {
            "type": "string",
            "format": "date"
          },
          "end_date": {
            "type": "string",
            "format": "date"
          },
          "address": {
            "type": "string",
            "description": "Object address or district"
          },
          "delivery": {
            "type": "boolean"
          },
          "comment": {
            "type": "string",
            "maxLength": 600
          },
          "dry_run": {
            "type": "boolean",
            "description": "Validate only, send nothing"
          },
          "idempotency_key": {
            "type": "string"
          }
        }
      },
      "BatchInput": {
        "type": "object",
        "required": [
          "items",
          "address"
        ],
        "properties": {
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "items": {
              "type": "object",
              "required": [
                "ref"
              ],
              "properties": {
                "ref": {
                  "type": "string",
                  "example": "rent-123"
                },
                "start_date": {
                  "type": "string",
                  "format": "date"
                },
                "end_date": {
                  "type": "string",
                  "format": "date"
                },
                "delivery": {
                  "type": "boolean"
                },
                "comment": {
                  "type": "string"
                }
              }
            }
          },
          "start_date": {
            "type": "string",
            "format": "date"
          },
          "end_date": {
            "type": "string",
            "format": "date"
          },
          "address": {
            "type": "string"
          },
          "delivery": {
            "type": "boolean"
          },
          "comment": {
            "type": "string",
            "maxLength": 600
          },
          "dry_run": {
            "type": "boolean"
          },
          "idempotency_key": {
            "type": "string"
          }
        }
      },
      "SuperRequestInput": {
        "type": "object",
        "required": [
          "address",
          "start_date",
          "end_date",
          "equipment"
        ],
        "properties": {
          "address": {
            "type": "string",
            "description": "Site/address, at least 5 chars"
          },
          "city": {
            "type": "string"
          },
          "start_date": {
            "type": "string",
            "pattern": "^d{4}-d{2}-d{2}$"
          },
          "end_date": {
            "type": "string",
            "pattern": "^d{4}-d{2}-d{2}$"
          },
          "equipment": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "type": "object",
              "required": [
                "type",
                "quantity"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "description": "Equipment type in Russian, e.g. экскаватор"
                },
                "quantity": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 50
                },
                "start_date": {
                  "type": "string",
                  "pattern": "^d{4}-d{2}-d{2}$"
                },
                "end_date": {
                  "type": "string",
                  "pattern": "^d{4}-d{2}-d{2}$"
                },
                "note": {
                  "type": "string",
                  "maxLength": 120
                }
              }
            }
          },
          "works": {
            "type": "array",
            "maxItems": 15,
            "items": {
              "type": "string"
            }
          },
          "budget_kzt": {
            "type": "integer",
            "minimum": 0
          },
          "comment": {
            "type": "string",
            "maxLength": 600
          },
          "dry_run": {
            "type": "boolean"
          },
          "idempotency_key": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/equipment": {
      "get": {
        "operationId": "searchEquipment",
        "summary": "Search rental equipment",
        "parameters": [
          {
            "name": "equipment_type",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. экскаватор"
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. Алматы"
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "delivery_required",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "maximum": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of listings with refs"
          }
        }
      }
    },
    "/equipment/{ref}": {
      "get": {
        "operationId": "getEquipment",
        "summary": "Listing details",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "rent-123"
          }
        ],
        "responses": {
          "200": {
            "description": "Listing"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/equipment/{ref}/quote": {
      "get": {
        "operationId": "getQuote",
        "summary": "Estimated price, prepayment and availability",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "delivery",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Quote"
          }
        }
      }
    },
    "/bookings": {
      "post": {
        "operationId": "createBookingRequest",
        "summary": "Send a booking request to the owner (real-world action: confirm with the user first)",
        "security": [
          {
            "oauth2": [
              "orders:create"
            ]
          },
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookingInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "dry_run result or duplicate"
          },
          "201": {
            "description": "Request sent to the owner"
          },
          "401": {
            "description": "Sign-in required"
          },
          "429": {
            "description": "Daily limit or rate limit"
          }
        }
      },
      "get": {
        "operationId": "listBookings",
        "summary": "My recent booking requests",
        "security": [
          {
            "oauth2": [
              "orders:read"
            ]
          },
          {
            "bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "List"
          }
        }
      }
    },
    "/bookings/{id}": {
      "get": {
        "operationId": "getBooking",
        "summary": "Booking status: pending, accepted, declined, cancelled, expired",
        "security": [
          {
            "oauth2": [
              "orders:read"
            ]
          },
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Booking"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/bookings/{id}/cancel": {
      "post": {
        "operationId": "cancelBooking",
        "summary": "Cancel a pending or accepted booking",
        "security": [
          {
            "oauth2": [
              "orders:create"
            ]
          },
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cancelled"
          }
        }
      }
    },
    "/bookings/{id}/payment-link": {
      "get": {
        "operationId": "getPaymentLink",
        "summary": "Page where the client pays the prepayment (the agent cannot pay)",
        "security": [
          {
            "oauth2": [
              "orders:read"
            ]
          },
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Link"
          }
        }
      }
    },
    "/bookings/batch": {
      "post": {
        "operationId": "createBookingBatch",
        "summary": "Send up to 5 booking requests at once (different equipment, one site). Real-world action: confirm with the user first",
        "security": [
          {
            "oauth2": [
              "orders:create"
            ]
          },
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "dry_run result"
          },
          "201": {
            "description": "Requests sent, batch_id returned"
          },
          "401": {
            "description": "Sign-in required"
          }
        }
      }
    },
    "/batches/{batch_id}": {
      "get": {
        "operationId": "getBatch",
        "summary": "Batch summary: accepted N of M",
        "security": [
          {
            "oauth2": [
              "orders:read"
            ]
          },
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "name": "batch_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Batch status"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/super-requests": {
      "post": {
        "operationId": "createSuperRequest",
        "summary": "Create one big request for several machines and jobs in the Requests section (owners get a \"created by AI\" label). Real-world action: run dry_run first and get client consent; owners who respond see the client phone. Publication is paid by the client on the site unless free publishing is enabled",
        "security": [
          {
            "oauth2": [
              "orders:create"
            ]
          },
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SuperRequestInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "dry_run preview, or duplicate of an existing request"
          },
          "201": {
            "description": "Created: status awaiting_payment (pay_url for the client) or published"
          },
          "400": {
            "description": "Validation error, see code (unknown_type, rules_required, daily_limit...)"
          },
          "401": {
            "description": "Sign-in required"
          }
        }
      }
    },
    "/super-requests/{super_order_id}": {
      "get": {
        "operationId": "getSuperRequest",
        "summary": "Status of a super request: awaiting_payment, payment_under_review, published, rejected; responses count once published",
        "security": [
          {
            "oauth2": [
              "orders:read"
            ]
          },
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "name": "super_order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/access": {
      "get": {
        "operationId": "getAccessInfo",
        "summary": "Call first: guest or signed in, what works now, what unlocks after the client signs in",
        "responses": {
          "200": {
            "description": "Access level and capabilities"
          }
        }
      }
    }
  }
}