{"openapi":"3.1.0","info":{"title":"Japonal Quoting API","version":"1","description":"Personal API keys act as the staff member who created them, limited by the key's scopes. Errors are RFC 9457 problem details."},"servers":[{"url":"https://api.japon-prod.tech"}],"security":[{"apiKey":[]}],"paths":{"/v1/me":{"get":{"operationId":"me.get","summary":"Who am I","description":"Returns the key's owner, agency and the key itself (name, prefix, scopes, expiry). Works with any scope; use it to check a key.","x-scopes":[],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["me"]},"userId":{"type":"string","format":"uuid"},"agencyId":{"type":"string","format":"uuid"},"agencyName":{"type":"string","nullable":true},"displayName":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"keyName":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["trips:read","trips:write","quotes:read","quotes:write","templates:read","templates:write","catalog:read","catalog:write","travelers:read","travelers:write"]}},"expiresAt":{"type":"string","nullable":true}},"required":["object","userId","agencyId","agencyName","displayName","email","keyName","keyPrefix","scopes","expiresAt"],"additionalProperties":false}}}},"default":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/trips":{"get":{"operationId":"trips.list","summary":"List trips","description":"Lists the trips the key's owner can see, newest change first by default. Filter by commercial state, owner, start date or metadata (`metadata[hubspotDealId]=123`). Poll for changes with `updatedSince` and `sort=updatedAt`, following `nextCursor` until it is null.","x-scopes":["trips:read"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"updatedSince","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["updatedAt","-updatedAt"],"default":"-updatedAt"}},{"name":"commercial","in":"query","required":false,"schema":{"type":"string","enum":["nueva","propuesta_enviada","aceptada","reserva_provisional","reservada","rechazada","cancelada"]}},{"name":"ownerId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"startFrom","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"startTo","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"metadata","in":"query","required":false,"schema":{"type":"object","additionalProperties":{"type":"string","maxLength":500}},"style":"deepObject","explode":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["trip"]},"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"title":{"type":"string"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"travelers":{"type":"integer"},"commercialState":{"type":"string","enum":["nueva","propuesta_enviada","aceptada","reserva_provisional","reservada","rechazada","cancelada"]},"ownerId":{"type":"string","format":"uuid","nullable":true},"coverImageUrl":{"type":"string","nullable":true},"design":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"originCity":{"type":"string"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"city":{"type":"string"},"nights":{"type":"integer","minimum":0,"maximum":365},"transferBefore":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"escala":{"type":"boolean","default":false},"place":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["id","city","nights","transferBefore"],"additionalProperties":false},"maxItems":60},"returnCity":{"type":"string","nullable":true},"returnTransfer":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"originPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}},"returnPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["version","originCity","stops","returnCity","returnTransfer"],"additionalProperties":false,"nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["object","id","code","title","startDate","endDate","travelers","commercialState","ownerId","coverImageUrl","design","metadata","createdAt","updatedAt"],"additionalProperties":false}},"nextCursor":{"type":"string","nullable":true}},"required":["object","data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"trips.create","summary":"Create a trip","description":"Creates a trip owned by the key's owner, optionally tagged with metadata. Send an `Idempotency-Key` header so a retried request returns the same trip. `dryRun=true` validates and returns the trip without creating it.","x-scopes":["trips:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and body return the first response (kept 24 hours).","schema":{"type":"string","maxLength":255}},{"name":"dryRun","in":"query","required":false,"description":"Validate and return the result without writing.","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500,"nullable":true}}},"required":["title"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["trip"]},"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"title":{"type":"string"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"travelers":{"type":"integer"},"commercialState":{"type":"string","enum":["nueva","propuesta_enviada","aceptada","reserva_provisional","reservada","rechazada","cancelada"]},"ownerId":{"type":"string","format":"uuid","nullable":true},"coverImageUrl":{"type":"string","nullable":true},"design":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"originCity":{"type":"string"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"city":{"type":"string"},"nights":{"type":"integer","minimum":0,"maximum":365},"transferBefore":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"escala":{"type":"boolean","default":false},"place":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["id","city","nights","transferBefore"],"additionalProperties":false},"maxItems":60},"returnCity":{"type":"string","nullable":true},"returnTransfer":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"originPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}},"returnPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["version","originCity","stops","returnCity","returnTransfer"],"additionalProperties":false,"nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["object","id","code","title","startDate","endDate","travelers","commercialState","ownerId","coverImageUrl","design","metadata","createdAt","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/trips/{tripId}":{"get":{"operationId":"trips.get","summary":"Get a trip","description":"Returns one trip with its design and metadata. 404 when it does not exist or the key's owner cannot see it.","x-scopes":["trips:read"],"parameters":[{"name":"tripId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["trip"]},"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"title":{"type":"string"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"travelers":{"type":"integer"},"commercialState":{"type":"string","enum":["nueva","propuesta_enviada","aceptada","reserva_provisional","reservada","rechazada","cancelada"]},"ownerId":{"type":"string","format":"uuid","nullable":true},"coverImageUrl":{"type":"string","nullable":true},"design":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"originCity":{"type":"string"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"city":{"type":"string"},"nights":{"type":"integer","minimum":0,"maximum":365},"transferBefore":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"escala":{"type":"boolean","default":false},"place":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["id","city","nights","transferBefore"],"additionalProperties":false},"maxItems":60},"returnCity":{"type":"string","nullable":true},"returnTransfer":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"originPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}},"returnPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["version","originCity","stops","returnCity","returnTransfer"],"additionalProperties":false,"nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["object","id","code","title","startDate","endDate","travelers","commercialState","ownerId","coverImageUrl","design","metadata","createdAt","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"operationId":"trips.update","summary":"Update a trip","description":"Changes a trip's title, dates, number of travelers, owner or metadata; only the fields sent change (`null` clears a date or deletes a metadata key). Refuses changing travelers while a quote is accepted (`pax_locked`) or below the roster (`pax_below_roster`), and an owner who is not active staff (`owner_not_staff`). `dryRun=true` returns the result without writing.","x-scopes":["trips:write"],"parameters":[{"name":"tripId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and body return the first response (kept 24 hours).","schema":{"type":"string","maxLength":255}},{"name":"dryRun","in":"query","required":false,"description":"Validate and return the result without writing.","schema":{"type":"boolean"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"travelers":{"type":"integer","minimum":1,"maximum":40},"ownerId":{"type":"string","format":"uuid"},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500,"nullable":true}}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["trip"]},"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"title":{"type":"string"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"travelers":{"type":"integer"},"commercialState":{"type":"string","enum":["nueva","propuesta_enviada","aceptada","reserva_provisional","reservada","rechazada","cancelada"]},"ownerId":{"type":"string","format":"uuid","nullable":true},"coverImageUrl":{"type":"string","nullable":true},"design":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"originCity":{"type":"string"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"city":{"type":"string"},"nights":{"type":"integer","minimum":0,"maximum":365},"transferBefore":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"escala":{"type":"boolean","default":false},"place":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["id","city","nights","transferBefore"],"additionalProperties":false},"maxItems":60},"returnCity":{"type":"string","nullable":true},"returnTransfer":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"originPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}},"returnPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["version","originCity","stops","returnCity","returnTransfer"],"additionalProperties":false,"nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["object","id","code","title","startDate","endDate","travelers","commercialState","ownerId","coverImageUrl","design","metadata","createdAt","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"operationId":"trips.archive","summary":"Archive a trip","description":"Archives the trip (it leaves the lists; restore it with POST /trips/{tripId}/restore). Refused when the key's owner may not archive it (`delete_forbidden`).","x-scopes":["trips:write"],"parameters":[{"name":"tripId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and body return the first response (kept 24 hours).","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["trip_archived"]},"id":{"type":"string","format":"uuid"}},"required":["object","id"],"additionalProperties":false}}}},"default":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/trips/{tripId}/commercial-state":{"post":{"operationId":"trips.setCommercialState","summary":"Set a trip's commercial state","description":"Moves the trip to another commercial state (nueva, propuesta_enviada, aceptada, …). It does not email anyone and is not undoable through the API. Setting the current state is refused (`commercial_no_op`).","x-scopes":["trips:write"],"parameters":[{"name":"tripId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and body return the first response (kept 24 hours).","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["nueva","propuesta_enviada","aceptada","reserva_provisional","reservada","rechazada","cancelada"]}},"required":["state"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["trip"]},"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"title":{"type":"string"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"travelers":{"type":"integer"},"commercialState":{"type":"string","enum":["nueva","propuesta_enviada","aceptada","reserva_provisional","reservada","rechazada","cancelada"]},"ownerId":{"type":"string","format":"uuid","nullable":true},"coverImageUrl":{"type":"string","nullable":true},"design":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"originCity":{"type":"string"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"city":{"type":"string"},"nights":{"type":"integer","minimum":0,"maximum":365},"transferBefore":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"escala":{"type":"boolean","default":false},"place":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["id","city","nights","transferBefore"],"additionalProperties":false},"maxItems":60},"returnCity":{"type":"string","nullable":true},"returnTransfer":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"originPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}},"returnPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["version","originCity","stops","returnCity","returnTransfer"],"additionalProperties":false,"nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["object","id","code","title","startDate","endDate","travelers","commercialState","ownerId","coverImageUrl","design","metadata","createdAt","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/trips/{tripId}/design":{"put":{"operationId":"trips.setDesign","summary":"Replace a trip's design","description":"Replaces the trip's design (route, stops and transfers) as a whole, and mirrors transport hours into the trip's quotes. `dryRun=true` validates and returns the trip without writing.","x-scopes":["trips:write"],"parameters":[{"name":"tripId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and body return the first response (kept 24 hours).","schema":{"type":"string","maxLength":255}},{"name":"dryRun","in":"query","required":false,"description":"Validate and return the result without writing.","schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"design":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"originCity":{"type":"string"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"city":{"type":"string"},"nights":{"type":"integer","minimum":0,"maximum":365},"transferBefore":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"escala":{"type":"boolean","default":false},"place":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["id","city","nights","transferBefore"],"additionalProperties":false},"maxItems":60},"returnCity":{"type":"string","nullable":true},"returnTransfer":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"originPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}},"returnPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["version","originCity","stops","returnCity","returnTransfer"],"additionalProperties":false}},"required":["design"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["trip"]},"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"title":{"type":"string"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"travelers":{"type":"integer"},"commercialState":{"type":"string","enum":["nueva","propuesta_enviada","aceptada","reserva_provisional","reservada","rechazada","cancelada"]},"ownerId":{"type":"string","format":"uuid","nullable":true},"coverImageUrl":{"type":"string","nullable":true},"design":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"originCity":{"type":"string"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"city":{"type":"string"},"nights":{"type":"integer","minimum":0,"maximum":365},"transferBefore":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"escala":{"type":"boolean","default":false},"place":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["id","city","nights","transferBefore"],"additionalProperties":false},"maxItems":60},"returnCity":{"type":"string","nullable":true},"returnTransfer":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"originPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}},"returnPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["version","originCity","stops","returnCity","returnTransfer"],"additionalProperties":false,"nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["object","id","code","title","startDate","endDate","travelers","commercialState","ownerId","coverImageUrl","design","metadata","createdAt","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/trips/{tripId}/restore":{"post":{"operationId":"trips.restore","summary":"Restore an archived trip","description":"Restores an archived trip. 404 when it is not archived or the key's owner may not restore it.","x-scopes":["trips:write"],"parameters":[{"name":"tripId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retries with the same key and body return the first response (kept 24 hours).","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["trip"]},"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"title":{"type":"string"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"travelers":{"type":"integer"},"commercialState":{"type":"string","enum":["nueva","propuesta_enviada","aceptada","reserva_provisional","reservada","rechazada","cancelada"]},"ownerId":{"type":"string","format":"uuid","nullable":true},"coverImageUrl":{"type":"string","nullable":true},"design":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"originCity":{"type":"string"},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"city":{"type":"string"},"nights":{"type":"integer","minimum":0,"maximum":365},"transferBefore":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"escala":{"type":"boolean","default":false},"place":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["id","city","nights","transferBefore"],"additionalProperties":false},"maxItems":60},"returnCity":{"type":"string","nullable":true},"returnTransfer":{"type":"object","properties":{"id":{"type":"string"},"departDate":{"type":"string","nullable":true},"arriveDate":{"type":"string","nullable":true},"days":{"type":"integer","minimum":0,"maximum":30,"default":0},"departTime":{"type":"string","default":""},"arriveTime":{"type":"string","default":""},"flight":{"type":"object","properties":{"flightNo":{"type":"string","default":""},"airline":{"type":"string","default":""},"fromAirport":{"type":"string","default":""},"toAirport":{"type":"string","default":""},"source":{"type":"string","default":""},"fetchedAt":{"type":"string","default":""},"scheduleValidFor":{"type":"string","default":""}},"additionalProperties":false,"default":{"flightNo":"","airline":"","fromAirport":"","toAirport":"","source":"","fetchedAt":"","scheduleValidFor":""}}},"required":["id","departDate","arriveDate"],"additionalProperties":false,"nullable":true},"originPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}},"returnPlace":{"type":"object","properties":{"placeId":{"type":"string","default":""},"lat":{"type":"number","nullable":true,"default":null},"lng":{"type":"number","nullable":true,"default":null},"formattedAddress":{"type":"string","default":""}},"additionalProperties":false,"default":{"placeId":"","lat":null,"lng":null,"formattedAddress":""}}},"required":["version","originCity","stops","returnCity","returnTransfer"],"additionalProperties":false,"nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["object","id","code","title","startDate","endDate","travelers","commercialState","ownerId","coverImageUrl","design","metadata","createdAt","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/trips/archived":{"get":{"operationId":"trips.listArchived","summary":"List archived trips","description":"Lists archived trips the key's owner may restore, most recently archived first. Returns at most `limit` rows; `nextCursor` is always null.","x-scopes":["trips:read"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["archived_trip"]},"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"title":{"type":"string"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"archivedAt":{"type":"string"},"archivedBy":{"type":"string","format":"uuid","nullable":true}},"required":["object","id","code","title","startDate","endDate","archivedAt","archivedBy"],"additionalProperties":false}},"nextCursor":{"type":"string","nullable":true}},"required":["object","data","nextCursor"],"additionalProperties":false}}}},"default":{"description":"Problem","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer"}},"schemas":{"Problem":{"type":"object","required":["type","title","status","detail","code","requestId"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}},"requestId":{"type":"string"}}}}}}