> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a reservation

> Books Reserved TPM: uncached input and output TPM on one model and service tier, for whole hours. The price is charged when you book. See [Reserved TPM](/reserved-tpm).

> [!NOTE]
>
> Reserved TPM is in Beta and available to select pilot customers. To join the
> waitlist, send us a note from the support form in your [Sail
> dashboard](https://app.sailresearch.com) (recommended), or [contact
> support](https://www.sailresearch.com/support).


## OpenAPI

````yaml /openapi.json post /reserved-tpm
openapi: 3.1.0
info:
  title: Sail API
  version: '2026-02-18'
  description: >-
    Sail provides OpenAI-compatible Responses and Chat Completions endpoints,
    plus an Anthropic-compatible Messages endpoint. This reference documents the
    currently supported subset of fields.
servers:
  - url: https://api.sailresearch.com/v1
security:
  - BearerAuth: []
tags:
  - name: Models API
    description: Model discovery endpoints.
  - name: Responses API
    description: OpenAI-compatible Responses API endpoints.
  - name: Chat Completions API
    description: OpenAI-compatible Chat Completions API endpoints.
  - name: Messages API
    description: Anthropic-compatible Messages API endpoints.
  - name: Batches API
    description: Submit and manage batches of requests.
  - name: Reserved TPM API
    description: Reserve throughput ahead of time. In Beta.
paths:
  /reserved-tpm:
    post:
      tags:
        - Reserved TPM API
      summary: Create a reservation
      description: >-
        Books Reserved TPM: uncached input and output TPM on one model and
        service tier, for whole hours. The price is charged when you book. See
        [Reserved TPM](/reserved-tpm).
      operationId: createReservedTpm
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
          description: >-
            Required. Identifies one reservation within your organization.
            Retrying with the same key and fields returns the same reservation.
            Reusing a key with different fields returns 409.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReservedTpmRequest'
            example:
              model: deepseek/deepseek-v4-pro-0813
              service_tier: flex
              starts_at: '2026-11-20T16:00:00Z'
              duration_hours: 4
              uncached_input_tpm: 1000000
              output_tpm: 200000
      responses:
        '200':
          description: >-
            An earlier request with this Idempotency-Key made this reservation.
            Returns it as it is now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservedTpmObject'
              example:
                id: rtpm_019a9b2c-4f1e-7a3d-9c2b-5e8f1a0d6b47
                object: reserved_tpm
                model: deepseek/deepseek-v4-pro-0813
                service_tier: flex
                starts_at: '2026-11-20T16:00:00Z'
                ends_at: '2026-11-20T20:00:00Z'
                duration_hours: 4
                uncached_input_tpm: 1000000
                output_tpm: 200000
                routing: null
                price:
                  amount_cents: 17712
                  currency: USD
                prepayment:
                  consumed_cents: 0
                  remaining_cents: 17712
                  as_of: null
                free_cancel_until: '2026-11-13T18:12:11Z'
                refund: null
                status: booked
                created_at: '2026-11-13T18:02:11Z'
                updated_at: '2026-11-13T18:02:11Z'
                cancelled_at: null
        '201':
          description: The reservation is booked and charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservedTpmObject'
              example:
                id: rtpm_019a9b2c-4f1e-7a3d-9c2b-5e8f1a0d6b47
                object: reserved_tpm
                model: deepseek/deepseek-v4-pro-0813
                service_tier: flex
                starts_at: '2026-11-20T16:00:00Z'
                ends_at: '2026-11-20T20:00:00Z'
                duration_hours: 4
                uncached_input_tpm: 1000000
                output_tpm: 200000
                routing: null
                price:
                  amount_cents: 17712
                  currency: USD
                prepayment:
                  consumed_cents: 0
                  remaining_cents: 17712
                  as_of: null
                free_cancel_until: '2026-11-13T18:12:11Z'
                refund: null
                status: booked
                created_at: '2026-11-13T18:02:11Z'
                updated_at: '2026-11-13T18:02:11Z'
                cancelled_at: null
        '202':
          description: >-
            Payment is still processing. The reservation is `pending_charge` and
            holds its capacity. Get it again to see the outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservedTpmObject'
              example:
                id: rtpm_019a9b2c-4f1e-7a3d-9c2b-5e8f1a0d6b47
                object: reserved_tpm
                model: deepseek/deepseek-v4-pro-0813
                service_tier: flex
                starts_at: '2026-11-20T16:00:00Z'
                ends_at: '2026-11-20T20:00:00Z'
                duration_hours: 4
                uncached_input_tpm: 1000000
                output_tpm: 200000
                routing: null
                price:
                  amount_cents: 17712
                  currency: USD
                prepayment: null
                free_cancel_until: null
                refund: null
                status: pending_charge
                created_at: '2026-11-13T18:02:11Z'
                updated_at: '2026-11-13T18:02:11Z'
                cancelled_at: null
        '400':
          description: >-
            Invalid request. Error codes include `reservation_below_minimum`,
            `model_not_available`, `service_tier_not_available`, and
            `us_only_not_available`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: >-
            Prepaid plans only: your credit balance must stay above the price
            (error code `credits_exhausted`). Add credits and book again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: >-
                    This reservation costs $177.12; your balance must stay above
                    that (it's $50.00). Add credits at
                    https://app.sailresearch.com/billing.
                  type: billing_error
                  param: null
                  code: credits_exhausted
        '403':
          description: >-
            Your organization doesn't have Reserved TPM access, isn't on a Pro
            or Enterprise plan, or can't be charged. Also returned for an API
            key that isn't an organization key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            `capacity_unavailable`: the requested window is fully booked.
            `idempotency_key_reused`: the Idempotency-Key was used with
            different fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservedTpmConflictResponse'
              example:
                error:
                  message: >-
                    Reserved TPM for this model is fully booked during the
                    requested window, counting the time hosts need to switch to
                    this model before it starts
                  type: conflict_error
                  param: null
                  code: capacity_unavailable
                earliest_start: '2026-11-21T02:00:00Z'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Reserved TPM is temporarily unavailable. Retry with the same
            Idempotency-Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CreateReservedTpmRequest:
      type: object
      required:
        - model
        - service_tier
        - starts_at
        - duration_hours
      properties:
        model:
          type: string
          description: The model to reserve.
        service_tier:
          type: string
          enum:
            - asap
            - balanced
            - flex
          description: The service tier to reserve.
        starts_at:
          type: string
          format: date-time
          description: >-
            When the reservation starts, as an RFC 3339 time. It must be at
            least 1 hour and at most 7 days away.
        duration_hours:
          type: integer
          minimum: 1
          maximum: 72
          description: Whole hours, from 1 to 72.
        uncached_input_tpm:
          type: integer
          minimum: 0
          description: Uncached input tokens per minute. Set this, `output_tpm`, or both.
        output_tpm:
          type: integer
          minimum: 0
          description: Output tokens per minute. Set this, `uncached_input_tpm`, or both.
        routing:
          type: object
          properties:
            allowed_countries:
              type: array
              items:
                type: string
                pattern: ^\s*[Uu][Ss]\s*$
              description: >-
                Set `["US"]` for a [US-only](/us-only-inference) reservation.
                Only `US` is supported.
          additionalProperties: false
      additionalProperties: false
    ReservedTpmObject:
      type: object
      required:
        - id
        - object
        - model
        - service_tier
        - starts_at
        - ends_at
        - duration_hours
        - uncached_input_tpm
        - output_tpm
        - routing
        - price
        - prepayment
        - free_cancel_until
        - refund
        - status
        - created_at
        - updated_at
        - cancelled_at
      properties:
        id:
          type: string
          pattern: ^rtpm_
          description: The reservation ID. It starts with `rtpm_`.
        object:
          type: string
          enum:
            - reserved_tpm
        model:
          type: string
          description: The reserved model.
        service_tier:
          type: string
          enum:
            - asap
            - balanced
            - flex
          description: The reserved service tier.
        starts_at:
          type: string
          format: date-time
          description: When the reservation starts.
        ends_at:
          type: string
          format: date-time
          description: When the reservation ends.
        duration_hours:
          type: integer
          description: The reservation's length in hours.
        uncached_input_tpm:
          type: integer
          description: Reserved uncached input tokens per minute.
        output_tpm:
          type: integer
          description: Reserved output tokens per minute.
        routing:
          description: Where the reservation's requests run, or null when unrestricted.
          oneOf:
            - $ref: '#/components/schemas/ReservedTpmRouting'
            - type: 'null'
        price:
          description: What the reservation costs, or null when it is not charged.
          oneOf:
            - $ref: '#/components/schemas/ReservedTpmPrice'
            - type: 'null'
        prepayment:
          description: >-
            How much of the prepaid price is used and left. Null unless the
            reservation was charged and is `booked` or `cancelled`, and null
            after a refund. It can keep updating for a few hours after the
            reservation ends.
          oneOf:
            - $ref: '#/components/schemas/ReservedTpmPrepayment'
            - type: 'null'
        current_minute:
          description: >-
            How much of the reservation's uncached input and output TPM is left
            in the current minute, or null when it isn't running. Only Get a
            reservation returns it. See [Get a
            reservation](/reserved-tpm#get-a-reservation).
          oneOf:
            - $ref: '#/components/schemas/ReservedTpmCurrentMinute'
            - type: 'null'
        free_cancel_until:
          description: >-
            When a free cancel stops being available, or null when cancelling
            now would not be refunded. See [Cancel a
            reservation](/reserved-tpm#cancel-a-reservation).
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
        refund:
          description: The refund of a free cancel, or null.
          oneOf:
            - $ref: '#/components/schemas/ReservedTpmRefund'
            - type: 'null'
        status:
          type: string
          enum:
            - pending_charge
            - booked
            - charge_failed
            - cancelled
          description: >-
            `pending_charge` while payment is processing, then `booked`.
            `charge_failed` means nothing was charged and the capacity was
            released. `cancelled` means you cancelled it.
        created_at:
          type: string
          format: date-time
          description: When the reservation was made.
        updated_at:
          type: string
          format: date-time
          description: When the reservation last changed.
        cancelled_at:
          description: When you cancelled the reservation, or null.
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      additionalProperties: false
    ReservedTpmConflictResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
        earliest_start:
          description: >-
            Sent with `capacity_unavailable`: the earliest start at which the
            same reservation fits, up to the latest start your organization can
            book. Null when none does.
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
      additionalProperties: false
    ReservedTpmRouting:
      type: object
      required:
        - allowed_countries
      properties:
        allowed_countries:
          type: array
          items:
            type: string
          description: Country codes the reservation's requests run in, such as `["US"]`.
      additionalProperties: false
    ReservedTpmPrice:
      type: object
      required:
        - amount_cents
        - currency
      properties:
        amount_cents:
          type: integer
          minimum: 0
          description: The price in cents.
        currency:
          type: string
          enum:
            - USD
      additionalProperties: false
    ReservedTpmPrepayment:
      type: object
      required:
        - consumed_cents
        - remaining_cents
        - as_of
      properties:
        consumed_cents:
          type: integer
          description: How much of the price your requests have used, in cents.
        remaining_cents:
          type: integer
          description: How much of the price is left, in cents.
        as_of:
          description: >-
            When usage was last measured. Null before the first measurement,
            when nothing is used.
          oneOf:
            - type: string
              format: date-time
            - type: 'null'
      additionalProperties: false
    ReservedTpmCurrentMinute:
      type: object
      required:
        - remaining_uncached_input_tokens
        - remaining_output_tokens
        - resets_at
      properties:
        remaining_uncached_input_tokens:
          type: integer
          description: Uncached input tokens left in the current minute.
        remaining_output_tokens:
          type: integer
          description: >-
            Output tokens left in the current minute. A covered request's output
            counts shortly after it finishes.
        resets_at:
          type: string
          format: date-time
          description: When the minute ends and the counts reset.
      additionalProperties: false
    ReservedTpmRefund:
      type: object
      required:
        - amount_cents
        - status
      properties:
        amount_cents:
          type: integer
          description: 'The refund in cents: the full price, as Sail credits.'
        status:
          type: string
          enum:
            - pending
            - refunded
          description: '`pending` until the credits are added, then `refunded`.'
      additionalProperties: false
    ErrorObject:
      type: object
      required:
        - message
        - type
      properties:
        message:
          type: string
        type:
          type: string
        param:
          oneOf:
            - type: string
            - type: 'null'
        code:
          oneOf:
            - type: string
            - type: integer
            - type: 'null'
      additionalProperties: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````