# Reservations ## Get Reservation Instance Types > Get instance types available for reservation.\ > \ > Returns the subset of public instance types that are currently\ > eligible for reservation. Instance types can be disabled for\ > reservation via the Unleash reservation-disabled-instance-types\ > feature flag. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"InstanceTypeModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"num_cpus":{"type":"integer","title":"Num Cpus"},"cpu_type":{"type":"string","title":"Cpu Type"},"ram_gb":{"type":"integer","title":"Ram Gb"},"num_gpus":{"type":"integer","title":"Num Gpus"},"gpu_type":{"type":"string","title":"Gpu Type"},"gpu_memory_gb":{"type":"integer","title":"Gpu Memory Gb"},"gpu_socket":{"type":"string","title":"Gpu Socket"},"local_storage_gb":{"type":"integer","title":"Local Storage Gb"},"network_type":{"type":"string","nullable":true},"ib_count":{"type":"integer","title":"Ib Count"},"bridge_count":{"type":"integer","title":"Bridge Count"}},"type":"object","required":["fid","name","num_cpus","cpu_type","ram_gb","num_gpus","gpu_type","gpu_memory_gb","gpu_socket","local_storage_gb","ib_count","bridge_count"],"title":"InstanceTypeModel"}}},"paths":{"/v2/reservation/instance-types":{"get":{"tags":["reservations","instance types"],"summary":"Get Reservation Instance Types","description":"Get instance types available for reservation.\n\nReturns the subset of public instance types that are currently\neligible for reservation. Instance types can be disabled for\nreservation via the Unleash reservation-disabled-instance-types\nfeature flag.","operationId":"get_reservation_instance_types_v2_reservation_instance_types_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/InstanceTypeModel"},"type":"array","title":"Response Get Reservation Instance Types V2 Reservation Instance Types Get"}}}}}}}}} ``` ## Get Reservation Quote > Get pricing offers for a reservation.\ > \ > Reservation offers are dynamic and the price may change slightly since\ > the time it was generated. You can include an optional "max\_unit\_price"\ > (which you can set at the quoted price or slightly above it) to ensure\ > your reservation request fails if the new price is above that max. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"ReservationQuoteResponse":{"properties":{"offers":{"items":{"$ref":"#/components/schemas/ReservationOffer"},"type":"array","title":"Offers"}},"type":"object","required":["offers"],"title":"ReservationQuoteResponse","description":"Response with all pricing offers available when creating a new reservation."},"ReservationOffer":{"properties":{"key":{"type":"string","title":"Key"},"display_name":{"type":"string","title":"Display Name"},"unit_price":{"type":"string","title":"Unit Price"},"return_buyback_price":{"type":"string","title":"Return Buyback Price"},"pause_buyback_price":{"type":"string","title":"Pause Buyback Price"},"total_price":{"type":"string","title":"Total Price"},"total_etbp_value":{"type":"string","title":"Total Etbp Value"},"total_fubp_value":{"type":"string","title":"Total Fubp Value"},"option_premium":{"type":"string","title":"Option Premium"}},"type":"object","required":["key","display_name","unit_price","return_buyback_price","pause_buyback_price","total_price","total_etbp_value","total_fubp_value","option_premium"],"title":"ReservationOffer","description":"A single pricing offer within a quote response."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/reservation/quote":{"get":{"tags":["reservations"],"summary":"Get Reservation Quote","description":"Get pricing offers for a reservation.\n\nReservation offers are dynamic and the price may change slightly since\nthe time it was generated. You can include an optional \"max_unit_price\"\n(which you can set at the quoted price or slightly above it) to ensure\nyour reservation request fails if the new price is above that max.","operationId":"get_reservation_quote_v2_reservation_quote_get","parameters":[{"name":"project","in":"query","required":true,"schema":{"type":"string","title":"Project"}},{"name":"instance_type","in":"query","required":true,"schema":{"type":"string","title":"Instance Type"}},{"name":"region","in":"query","required":true,"schema":{"type":"string","title":"Region"}},{"name":"start_time","in":"query","required":true,"schema":{"type":"string","format":"datetime","title":"Start Time"}},{"name":"end_time","in":"query","required":true,"schema":{"type":"string","format":"datetime","title":"End Time"}},{"name":"quantity","in":"query","required":true,"schema":{"type":"integer","minimum":1,"title":"Quantity"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationQuoteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Availability > Get availability information for reservations.\ > \ > This endpoint supports three different modes for querying availability:\ > \ > \## Mode: latest\_end\_time (default)\ > Get the latest possible end time for a reservation given a start time and\ > quantity.\ > \ > \*\*Required parameters:\*\*\ > \- \`start\_time\`: Desired start time for the reservation\ > \- \`quantity\`: Number of instances needed\ > \- \`project\`: Project FID\ > \- \`instance\_type\`: Instance type FID\ > \- \`region\`: Region name\ > \ > \*\*Returns:\*\* Latest possible end time and availability status\ > \ > \*\*Example:\*\*\ > \`\`\`\ > GET /reservation/availability?\ > start\_time=2024-01-01T00:00:00Z&\ > quantity=4&\ > project=proj\_01h8x2k9m3n4p5q6r7s8t9u0v&\ > instance\_type=it\_01h8x2k9m3n4p5q6r7s8t9u0v&\ > region=us-central1-a\ > \`\`\`\ > \ > \## Mode: slots\ > Get all available slots in a time range.\ > \ > \*\*Required parameters:\*\*\ > \- \`earliest\_start\_time\`: Start of the time range to search\ > \- \`latest\_end\_time\`: End of the time range to search\ > \- \`project\`: Project FID\ > \- \`instance\_type\`: Instance type FID\ > \- \`region\`: Region name\ > \ > \*\*Returns:\*\* List of available time slots with quantities\ > \ > \*\*Example:\*\*\ > \`\`\`\ > GET /reservation/availability?\ > mode=slots&\ > earliest\_start\_time=2024-01-01T00:00:00Z&\ > latest\_end\_time=2024-01-02T00:00:00Z&\ > project=proj\_01h8x2k9m3n4p5q6r7s8t9u0v&\ > instance\_type=it\_01h8x2k9m3n4p5q6r7s8t9u0v&\ > region=us-central1-a\ > \`\`\`\ > \ > \## Mode: check\ > Check if a specific time slot is available for reservation.\ > \ > \*\*Required parameters:\*\*\ > \- \`start\_time\`: Start of the desired time slot\ > \- \`end\_time\`: End of the desired time slot\ > \- \`quantity\`: Number of instances needed\ > \- \`project\`: Project FID\ > \- \`instance\_type\`: Instance type FID\ > \- \`region\`: Region name\ > \ > \*\*Returns:\*\* Boolean indicating if the slot is available\ > \ > \*\*Example:\*\*\ > \`\`\`\ > GET /reservation/availability?\ > mode=check&\ > start\_time=2024-01-01T00:00:00Z&\ > end\_time=2024-01-01T12:00:00Z&\ > quantity=4&\ > project=proj\_01h8x2k9m3n4p5q6r7s8t9u0v&\ > instance\_type=it\_01h8x2k9m3n4p5q6r7s8t9u0v&\ > region=us-central1-a\ > \`\`\`\ > \ > \## Common Parameters\ > All modes require these parameters:\ > \- \`project\`: Project FID\ > \- \`instance\_type\`: Instance type FID\ > \- \`region\`: Region name\ > \ > \## Authentication\ > Requires authentication and user must be a member of the specified project. ````json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"AvailabilitySlotModel":{"properties":{"start_time":{"type":"string","format":"datetime","title":"Start Time"},"end_time":{"type":"string","format":"datetime","title":"End Time"},"quantity":{"type":"integer","title":"Quantity"}},"type":"object","required":["start_time","end_time","quantity"],"title":"AvailabilitySlotModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/reservation/availability":{"get":{"tags":["reservations"],"summary":"Get Availability","description":"Get availability information for reservations.\n\nThis endpoint supports three different modes for querying availability:\n\n## Mode: latest_end_time (default)\nGet the latest possible end time for a reservation given a start time and\nquantity.\n\n**Required parameters:**\n- `start_time`: Desired start time for the reservation\n- `quantity`: Number of instances needed\n- `project`: Project FID\n- `instance_type`: Instance type FID\n- `region`: Region name\n\n**Returns:** Latest possible end time and availability status\n\n**Example:**\n```\nGET /reservation/availability?\n start_time=2024-01-01T00:00:00Z&\n quantity=4&\n project=proj_01h8x2k9m3n4p5q6r7s8t9u0v&\n instance_type=it_01h8x2k9m3n4p5q6r7s8t9u0v&\n region=us-central1-a\n```\n\n## Mode: slots\nGet all available slots in a time range.\n\n**Required parameters:**\n- `earliest_start_time`: Start of the time range to search\n- `latest_end_time`: End of the time range to search\n- `project`: Project FID\n- `instance_type`: Instance type FID\n- `region`: Region name\n\n**Returns:** List of available time slots with quantities\n\n**Example:**\n```\nGET /reservation/availability?\n mode=slots&\n earliest_start_time=2024-01-01T00:00:00Z&\n latest_end_time=2024-01-02T00:00:00Z&\n project=proj_01h8x2k9m3n4p5q6r7s8t9u0v&\n instance_type=it_01h8x2k9m3n4p5q6r7s8t9u0v&\n region=us-central1-a\n```\n\n## Mode: check\nCheck if a specific time slot is available for reservation.\n\n**Required parameters:**\n- `start_time`: Start of the desired time slot\n- `end_time`: End of the desired time slot\n- `quantity`: Number of instances needed\n- `project`: Project FID\n- `instance_type`: Instance type FID\n- `region`: Region name\n\n**Returns:** Boolean indicating if the slot is available\n\n**Example:**\n```\nGET /reservation/availability?\n mode=check&\n start_time=2024-01-01T00:00:00Z&\n end_time=2024-01-01T12:00:00Z&\n quantity=4&\n project=proj_01h8x2k9m3n4p5q6r7s8t9u0v&\n instance_type=it_01h8x2k9m3n4p5q6r7s8t9u0v&\n region=us-central1-a\n```\n\n## Common Parameters\nAll modes require these parameters:\n- `project`: Project FID\n- `instance_type`: Instance type FID\n- `region`: Region name\n\n## Authentication\nRequires authentication and user must be a member of the specified project.","operationId":"get_availability_v2_reservation_availability_get","parameters":[{"name":"project","in":"query","required":true,"schema":{"type":"string","title":"Project"}},{"name":"instance_type","in":"query","required":true,"schema":{"type":"string","title":"Instance Type"}},{"name":"region","in":"query","required":true,"schema":{"type":"string","title":"Region"}},{"name":"mode","in":"query","required":false,"schema":{"enum":["slots","latest_end_time","check"],"type":"string","default":"latest_end_time","title":"Mode"}},{"name":"earliest_start_time","in":"query","required":false,"schema":{"type":"string","format":"datetime","nullable":true}},{"name":"latest_end_time","in":"query","required":false,"schema":{"type":"string","format":"datetime","nullable":true}},{"name":"start_time","in":"query","required":false,"schema":{"type":"string","format":"datetime","nullable":true}},{"name":"end_time","in":"query","required":false,"schema":{"type":"string","format":"datetime","nullable":true}},{"name":"quantity","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"nullable":true}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AvailabilitySlotModel"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ```` ## Get Reservations > Get all reservations for a project ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"SortDirection":{"type":"string","enum":["asc","desc"]},"GetReservationsResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ReservationModel"},"type":"array","title":"Data"},"next_cursor":{"type":"string","nullable":true}},"type":"object","required":["data"],"title":"GetReservationsResponse"},"ReservationModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"project":{"type":"string","title":"Project"},"created_by":{"type":"string","title":"Created By"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deactivated_at":{"type":"string","format":"datetime","nullable":true},"instance_quantity":{"type":"integer","title":"Instance Quantity"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","nullable":true},"instances":{"items":{"type":"string"},"type":"array","title":"Instances"},"launch_specification":{"$ref":"#/components/schemas/LaunchSpecificationModel"},"status":{"type":"string","enum":["Pending","Active","Paused","Canceled","Ended"],"title":"Status"},"start_time":{"type":"string","format":"datetime","title":"Start Time"},"end_time":{"type":"string","format":"datetime","title":"End Time"},"total_price":{"type":"string","title":"Total Price"},"unit_price":{"type":"string","title":"Unit Price"}},"type":"object","required":["fid","name","project","created_by","created_at","instance_quantity","instance_type","instances","launch_specification","status","start_time","end_time","total_price","unit_price"],"title":"ReservationModel"},"LaunchSpecificationModel":{"properties":{"volumes":{"items":{"type":"string"},"type":"array","title":"Volumes","description":"List of volume FIDs"},"ssh_keys":{"items":{"type":"string"},"type":"array","title":"Ssh Keys","description":"List of SSH key FIDs"},"startup_script":{"type":"string","nullable":true},"kubernetes_cluster":{"type":"string","nullable":true},"image_version":{"type":"string","nullable":true},"memory_gb":{"type":"integer","nullable":true}},"type":"object","required":["volumes","ssh_keys"],"title":"LaunchSpecificationModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/reservation":{"get":{"tags":["reservations"],"summary":"Get Reservations","description":"Get all reservations for a project","operationId":"get_reservations_v2_reservation_get","parameters":[{"name":"next_cursor","in":"query","required":false,"schema":{"nullable":true}},{"name":"sort_by","in":"query","required":false,"schema":{"enum":["created_at","status"],"type":"string","nullable":true}},{"name":"sort_dir","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortDirection","nullable":true}},{"name":"project","in":"query","required":true,"schema":{"type":"string","title":"Project"}},{"name":"instance_type","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"region","in":"query","required":false,"schema":{"type":"string","nullable":true}},{"name":"status","in":"query","required":false,"schema":{"enum":["Pending","Active","Paused","Canceled","Ended"],"type":"string","nullable":true}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"nullable":true}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetReservationsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Create Reservation > Create a new reservation. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"CreateReservationRequest":{"properties":{"project":{"type":"string","title":"Project"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","title":"Region"},"start_time":{"type":"string","format":"datetime","title":"Start Time"},"end_time":{"type":"string","format":"datetime","title":"End Time"},"instance_quantity":{"type":"integer","title":"Instance Quantity"},"name":{"type":"string","title":"Name"},"launch_specification":{"$ref":"#/components/schemas/LaunchSpecificationModel"},"price_specification":{"$ref":"#/components/schemas/PriceSpecification","nullable":true}},"type":"object","required":["project","instance_type","region","start_time","end_time","instance_quantity","name","launch_specification"],"title":"CreateReservationRequest"},"LaunchSpecificationModel":{"properties":{"volumes":{"items":{"type":"string"},"type":"array","title":"Volumes","description":"List of volume FIDs"},"ssh_keys":{"items":{"type":"string"},"type":"array","title":"Ssh Keys","description":"List of SSH key FIDs"},"startup_script":{"type":"string","nullable":true},"kubernetes_cluster":{"type":"string","nullable":true},"image_version":{"type":"string","nullable":true},"memory_gb":{"type":"integer","nullable":true}},"type":"object","required":["volumes","ssh_keys"],"title":"LaunchSpecificationModel"},"PriceSpecification":{"properties":{"offer_key":{"type":"string","title":"Offer Key","default":"standard"},"max_unit_price":{"type":"integer","minimum":0,"nullable":true}},"type":"object","title":"PriceSpecification","description":"Optional pricing specification for flexible reservations.\n\nIf omitted, the reservation defaults to the 'standard' offer.\nIf provided, the system applies the specified offer's pricing."},"ReservationModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"project":{"type":"string","title":"Project"},"created_by":{"type":"string","title":"Created By"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deactivated_at":{"type":"string","format":"datetime","nullable":true},"instance_quantity":{"type":"integer","title":"Instance Quantity"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","nullable":true},"instances":{"items":{"type":"string"},"type":"array","title":"Instances"},"launch_specification":{"$ref":"#/components/schemas/LaunchSpecificationModel"},"status":{"type":"string","enum":["Pending","Active","Paused","Canceled","Ended"],"title":"Status"},"start_time":{"type":"string","format":"datetime","title":"Start Time"},"end_time":{"type":"string","format":"datetime","title":"End Time"},"total_price":{"type":"string","title":"Total Price"},"unit_price":{"type":"string","title":"Unit Price"}},"type":"object","required":["fid","name","project","created_by","created_at","instance_quantity","instance_type","instances","launch_specification","status","start_time","end_time","total_price","unit_price"],"title":"ReservationModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/reservation":{"post":{"tags":["reservations"],"summary":"Create Reservation","description":"Create a new reservation.","operationId":"create_reservation_v2_reservation_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReservationRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Extension Availability > Get extension availability for a reservation ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"ExtensionAvailabilityResponse":{"properties":{"latest_extension_time":{"type":"string","format":"datetime","title":"Latest Extension Time"},"available":{"type":"boolean","title":"Available"}},"type":"object","required":["latest_extension_time","available"],"title":"ExtensionAvailabilityResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/reservation/{reservation_fid}/extension-availability":{"get":{"tags":["reservations"],"summary":"Get Extension Availability","description":"Get extension availability for a reservation","operationId":"get_extension_availability_v2_reservation__reservation_fid__extension_availability_get","parameters":[{"name":"reservation_fid","in":"path","required":true,"schema":{"type":"string","title":"Reservation Fid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtensionAvailabilityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Extend Reservation > Extend a reservation to the requested time. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"ExtendReservationRequest":{"properties":{"end_time":{"type":"string","format":"datetime","title":"End Time"},"price_specification":{"$ref":"#/components/schemas/PriceSpecification","nullable":true}},"type":"object","required":["end_time"],"title":"ExtendReservationRequest"},"PriceSpecification":{"properties":{"offer_key":{"type":"string","title":"Offer Key","default":"standard"},"max_unit_price":{"type":"integer","minimum":0,"nullable":true}},"type":"object","title":"PriceSpecification","description":"Optional pricing specification for flexible reservations.\n\nIf omitted, the reservation defaults to the 'standard' offer.\nIf provided, the system applies the specified offer's pricing."},"ReservationModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"project":{"type":"string","title":"Project"},"created_by":{"type":"string","title":"Created By"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deactivated_at":{"type":"string","format":"datetime","nullable":true},"instance_quantity":{"type":"integer","title":"Instance Quantity"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","nullable":true},"instances":{"items":{"type":"string"},"type":"array","title":"Instances"},"launch_specification":{"$ref":"#/components/schemas/LaunchSpecificationModel"},"status":{"type":"string","enum":["Pending","Active","Paused","Canceled","Ended"],"title":"Status"},"start_time":{"type":"string","format":"datetime","title":"Start Time"},"end_time":{"type":"string","format":"datetime","title":"End Time"},"total_price":{"type":"string","title":"Total Price"},"unit_price":{"type":"string","title":"Unit Price"}},"type":"object","required":["fid","name","project","created_by","created_at","instance_quantity","instance_type","instances","launch_specification","status","start_time","end_time","total_price","unit_price"],"title":"ReservationModel"},"LaunchSpecificationModel":{"properties":{"volumes":{"items":{"type":"string"},"type":"array","title":"Volumes","description":"List of volume FIDs"},"ssh_keys":{"items":{"type":"string"},"type":"array","title":"Ssh Keys","description":"List of SSH key FIDs"},"startup_script":{"type":"string","nullable":true},"kubernetes_cluster":{"type":"string","nullable":true},"image_version":{"type":"string","nullable":true},"memory_gb":{"type":"integer","nullable":true}},"type":"object","required":["volumes","ssh_keys"],"title":"LaunchSpecificationModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/reservation/{reservation_fid}/extend":{"post":{"tags":["reservations"],"summary":"Extend Reservation","description":"Extend a reservation to the requested time.","operationId":"extend_reservation_v2_reservation__reservation_fid__extend_post","parameters":[{"name":"reservation_fid","in":"path","required":true,"schema":{"type":"string","title":"Reservation Fid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtendReservationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Update Reservation > Update a reservation's pause/resume status and/or volumes ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"UpdateReservationRequest":{"properties":{"paused":{"type":"boolean","nullable":true},"volumes":{"items":{"type":"string"},"type":"array","nullable":true}},"type":"object","title":"UpdateReservationRequest"},"ReservationModel":{"properties":{"fid":{"type":"string","title":"Fid"},"name":{"type":"string","title":"Name"},"project":{"type":"string","title":"Project"},"created_by":{"type":"string","title":"Created By"},"created_at":{"type":"string","format":"datetime","title":"Created At"},"deactivated_at":{"type":"string","format":"datetime","nullable":true},"instance_quantity":{"type":"integer","title":"Instance Quantity"},"instance_type":{"type":"string","title":"Instance Type"},"region":{"type":"string","nullable":true},"instances":{"items":{"type":"string"},"type":"array","title":"Instances"},"launch_specification":{"$ref":"#/components/schemas/LaunchSpecificationModel"},"status":{"type":"string","enum":["Pending","Active","Paused","Canceled","Ended"],"title":"Status"},"start_time":{"type":"string","format":"datetime","title":"Start Time"},"end_time":{"type":"string","format":"datetime","title":"End Time"},"total_price":{"type":"string","title":"Total Price"},"unit_price":{"type":"string","title":"Unit Price"}},"type":"object","required":["fid","name","project","created_by","created_at","instance_quantity","instance_type","instances","launch_specification","status","start_time","end_time","total_price","unit_price"],"title":"ReservationModel"},"LaunchSpecificationModel":{"properties":{"volumes":{"items":{"type":"string"},"type":"array","title":"Volumes","description":"List of volume FIDs"},"ssh_keys":{"items":{"type":"string"},"type":"array","title":"Ssh Keys","description":"List of SSH key FIDs"},"startup_script":{"type":"string","nullable":true},"kubernetes_cluster":{"type":"string","nullable":true},"image_version":{"type":"string","nullable":true},"memory_gb":{"type":"integer","nullable":true}},"type":"object","required":["volumes","ssh_keys"],"title":"LaunchSpecificationModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/reservation/{reservation_fid}":{"patch":{"tags":["reservations"],"summary":"Update Reservation","description":"Update a reservation's pause/resume status and/or volumes","operationId":"update_reservation_v2_reservation__reservation_fid__patch","parameters":[{"name":"reservation_fid","in":"path","required":true,"schema":{"type":"string","title":"Reservation Fid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateReservationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationModel"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Terminate Instance > Remove and permanently delete instances from this reservation.\ > \ > You will receive a credit based on your early termination buyback price\ > associated with this reservation and the time remaining in the\ > reservation.\ > \ > This endpoint does a best effort to termiante all instances, but it can\ > fail to do so for some instances. If you receive a 207, then please see\ > the response for details. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"TerminateInstanceRequest":{"properties":{"instances":{"items":{"type":"string"},"type":"array","minItems":1,"uniqueItems":true,"title":"Instances"},"reduce_capacity":{"type":"boolean","const":true,"title":"Reduce Capacity"}},"type":"object","required":["instances","reduce_capacity"],"title":"TerminateInstanceRequest"},"TerminateInstanceResponsePartialSuccess":{"properties":{"terminated_instances":{"items":{"type":"string"},"type":"array","uniqueItems":true,"title":"Terminated Instances"}},"type":"object","required":["terminated_instances"],"title":"TerminateInstanceResponsePartialSuccess"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/reservation/{reservation_fid}/terminate-instances":{"post":{"tags":["reservations"],"summary":"Terminate Instance","description":"Remove and permanently delete instances from this reservation.\n\nYou will receive a credit based on your early termination buyback price\nassociated with this reservation and the time remaining in the\nreservation.\n\nThis endpoint does a best effort to termiante all instances, but it can\nfail to do so for some instances. If you receive a 207, then please see\nthe response for details.","operationId":"terminate_instance_v2_reservation__reservation_fid__terminate_instances_post","parameters":[{"name":"reservation_fid","in":"path","required":true,"schema":{"type":"string","title":"Reservation Fid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TerminateInstanceRequest"}}}},"responses":{"200":{"description":"Successfully terminated all instances.","content":{"application/json":{"schema":{}}}},"207":{"description":"Failed to terminate some instances. See response for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TerminateInstanceResponsePartialSuccess"}}}},"400":{"description":"The reservation was already ended."},"404":{"description":"Either the reservation or one of the instances could not be found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"502":{"description":"No instance was able to be stopped due to an internal error."}}}}}} ``` ## Get Reservation History > Get the activity history for a reservation.\ > \ > Returns a chronological list of order-level status changes (Placed, Active,\ > Paused, Resumed, Canceled, Ended) interleaved with aggregated instance-level\ > status events (instances running, stopped, error) bucketed into 60-second\ > windows so burst transitions appear as a single entry. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"ReservationHistoryResponse":{"properties":{"reservation_fid":{"type":"string","title":"Reservation Fid"},"events":{"items":{"$ref":"#/components/schemas/ReservationHistoryEventModel"},"type":"array","title":"Events","description":"List of historical events for this reservation, ordered by time"}},"type":"object","required":["reservation_fid","events"],"title":"ReservationHistoryResponse","description":"Response model for reservation history."},"ReservationHistoryEventModel":{"properties":{"timestamp":{"type":"string","format":"datetime","title":"Timestamp","description":"When the event occurred"},"event_type":{"type":"string","enum":["Placed","Active","Paused","Resumed","Canceled","Ended","Terms Set","Terms Changed"],"title":"Event Type"},"user_id":{"type":"string","nullable":true},"unit_price_cents":{"type":"integer","nullable":true},"pause_credit_cents":{"type":"integer","nullable":true},"return_credit_cents":{"type":"integer","nullable":true}},"type":"object","required":["timestamp","event_type"],"title":"ReservationHistoryEventModel","description":"A single event in the history of a reservation."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/reservation/{reservation_fid}/history":{"get":{"tags":["reservations"],"summary":"Get Reservation History","description":"Get the activity history for a reservation.\n\nReturns a chronological list of order-level status changes (Placed, Active,\nPaused, Resumed, Canceled, Ended) interleaved with aggregated instance-level\nstatus events (instances running, stopped, error) bucketed into 60-second\nwindows so burst transitions appear as a single entry.","operationId":"get_reservation_history_v2_reservation__reservation_fid__history_get","parameters":[{"name":"reservation_fid","in":"path","required":true,"schema":{"type":"string","title":"Reservation Fid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Reservation Usage > Get usage breakdown for a flex reservation. ```json {"openapi":"3.1.0","info":{"title":"Mithril","version":"1.0.0"},"servers":[{"url":"https://api.mithril.ai"}],"security":[{"MithrilAPIKey":[]}],"components":{"securitySchemes":{"MithrilAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"fkey_"}},"schemas":{"ReservationUsageResponse":{"properties":{"reservation":{"$ref":"#/components/schemas/ReservationInfoModel"},"summary":{"$ref":"#/components/schemas/UsageSummaryModel"},"grants":{"items":{"$ref":"#/components/schemas/GrantUsageModel"},"type":"array","title":"Grants"},"pricing_events":{"items":{"$ref":"#/components/schemas/PricingEventModel"},"type":"array","title":"Pricing Events"},"reservation_events":{"items":{"$ref":"#/components/schemas/ReservationLevelEventModel"},"type":"array","title":"Reservation Events"}},"type":"object","required":["reservation","summary","grants","pricing_events","reservation_events"],"title":"ReservationUsageResponse"},"ReservationInfoModel":{"properties":{"fid":{"type":"string","title":"Fid"},"order_name":{"type":"string","title":"Order Name"},"start_date":{"type":"string","format":"datetime","title":"Start Date"},"end_date":{"type":"string","format":"datetime","title":"End Date"},"status":{"type":"string","enum":["Open","Allocated","Preempting","Terminated","Paused"]},"committed_cost_cents":{"type":"integer","title":"Committed Cost Cents"}},"type":"object","required":["fid","order_name","start_date","end_date","status","committed_cost_cents"],"title":"ReservationInfoModel"},"UsageSummaryModel":{"properties":{"committed_cost_cents":{"type":"integer","title":"Committed Cost Cents"},"flex_use_credits_cents":{"type":"integer","title":"Flex Use Credits Cents"},"early_termination_credits_cents":{"type":"integer","title":"Early Termination Credits Cents"},"net_cost_cents":{"type":"integer","title":"Net Cost Cents"},"reserved_instance_hours":{"type":"string","format":"duration","title":"Reserved Instance Hours"},"active_instance_hours":{"type":"string","format":"duration","title":"Active Instance Hours"},"idle_instance_hours":{"type":"string","format":"duration","title":"Idle Instance Hours"},"as_of":{"type":"string","format":"datetime","title":"As Of"}},"type":"object","required":["committed_cost_cents","flex_use_credits_cents","early_termination_credits_cents","net_cost_cents","reserved_instance_hours","active_instance_hours","idle_instance_hours","as_of"],"title":"UsageSummaryModel"},"GrantUsageModel":{"properties":{"fid":{"type":"string","title":"Fid"},"starts_at":{"type":"string","format":"datetime","title":"Starts At"},"ends_at":{"type":"string","format":"datetime","title":"Ends At"},"quantity":{"type":"integer","title":"Quantity"},"unit_price":{"type":"integer","title":"Unit Price"},"price_credit":{"type":"integer","title":"Price Credit"},"return_credit":{"type":"integer","title":"Return Credit"}},"type":"object","required":["fid","starts_at","ends_at","quantity","unit_price","price_credit","return_credit"],"title":"GrantUsageModel"},"PricingEventModel":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"occurred_at":{"type":"string","format":"datetime","title":"Occurred At"},"instance_fid":{"type":"string","title":"Instance Fid"},"instance_name":{"type":"string","title":"Instance Name"},"instance_status":{"type":"string","enum":["STATUS_NEW","STATUS_CONFIRMED","STATUS_INITIALIZING","STATUS_STARTING","STATUS_RUNNING","STATUS_STOPPING","STATUS_TERMINATED","STATUS_RELOCATING","STATUS_PREEMPTING","STATUS_PREEMPTED","STATUS_REPLACED","STATUS_PAUSED","STATUS_ERROR"],"title":"Instance Status"}},"type":"object","required":["id","occurred_at","instance_fid","instance_name","instance_status"],"title":"PricingEventModel"},"ReservationLevelEventModel":{"properties":{"occurred_at":{"type":"string","format":"datetime","title":"Occurred At"},"event_type":{"type":"string","enum":["Started","Paused","Extended"],"title":"Event Type"},"reservation_name":{"type":"string","title":"Reservation Name"}},"type":"object","required":["occurred_at","event_type","reservation_name"],"title":"ReservationLevelEventModel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v2/reservation/{reservation_fid}/usage":{"get":{"tags":["reservations"],"summary":"Get Reservation Usage","description":"Get usage breakdown for a flex reservation.","operationId":"get_reservation_usage_v2_reservation__reservation_fid__usage_get","parameters":[{"name":"reservation_fid","in":"path","required":true,"schema":{"type":"string","title":"Reservation Fid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.mithril.ai/compute-api/compute-api-reference/reservations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.