Together AI Endpoints API

openapi: 3.2.0
info:
  title: Together Endpoints API
  description: The Together REST API. Please see https://docs.together.ai for more details.
  version: 2.0.0
  termsOfService: https://www.together.ai/terms-of-service
  contact:
    name: Together Support
    url: https://www.together.ai/contact
  license:
    name: MIT
    url: https://github.com/togethercomputer/openapi/blob/main/LICENSE
servers:
- url: https://api.together.ai/v1
security:
- bearerAuth: []
tags:
- name: Endpoints
paths:
  /endpoints:
    get:
      tags:
      - Endpoints
      summary: List all endpoints, can be filtered by type
      description: Returns a list of all endpoints associated with your account. You can filter the results by type (dedicated or serverless).
      x-codeSamples:
      - lang: Python
        label: Together AI SDK (v2)
        source: "# Docs for v1 can be found by changing the above selector ^\nfrom together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nresponse = client.endpoints.list()\n\nfor endpoint in response.data:\n    print(endpoint.id)\n"
      - lang: Python
        label: Together AI SDK (v1)
        source: "from together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nendpoints = client.endpoints.list()\n\nfor endpoint in endpoints:\n    print(endpoint.id)\n"
      - lang: TypeScript
        label: Together AI SDK (TypeScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst endpoints = await client.endpoints.list();\n\nfor (const endpoint of endpoints.data) {\n  console.log(endpoint);\n}\n"
      - lang: JavaScript
        label: Together AI SDK (JavaScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst endpoints = await client.endpoints.list();\n\nfor (const endpoint of endpoints.data) {\n  console.log(endpoint);\n}\n"
      - lang: Shell
        label: cURL
        source: "curl \"https://api.together.ai/v1/endpoints\" \\\n     -H \"Authorization: Bearer $TOGETHER_API_KEY\" \\\n     -H \"Content-Type: application/json\"\n"
      operationId: listEndpoints
      parameters:
      - name: type
        in: query
        required: false
        schema:
          description: Filter endpoints by type
          type: string
          enum:
          - dedicated
          - serverless
      - name: usage_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - on-demand
          - reserved
          description: Filter endpoints by usage type
      - name: mine
        in: query
        required: false
        schema:
          type: boolean
          description: If true, return only endpoints owned by the caller
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                - data
                properties:
                  object:
                    description: The object type, which is always `list`.
                    const: list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ListEndpoint'
                example:
                  object: list
                  data:
                  - object: endpoint
                    id: endpoint-5c0c20db-62fe-4f41-8ffc-d9e4ea1a264e
                    name: allenai/OLMo-7B
                    model: allenai/OLMo-7B
                    type: serverless
                    owner: together
                    state: STARTED
                    created_at: '2024-02-28T21:34:35.444Z'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
    post:
      tags:
      - Endpoints
      summary: Create a dedicated endpoint, it will start automatically
      description: Creates a new dedicated endpoint for serving models. The endpoint will automatically start after creation. You can deploy any supported model on hardware configurations that meet the model's requirements.
      x-codeSamples:
      - lang: Python
        label: Together AI SDK (v2)
        source: "# Docs for v1 can be found by changing the above selector ^\nfrom together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nendpoint = client.endpoints.create(\n    model=\"Qwen/Qwen3.5-9B-FP8\",\n    hardware=\"1x_nvidia_a100_80gb_sxm\",\n    autoscaling={\n      \"min_replicas\": 2,\n      \"max_replicas\": 5,\n    }\n)\n\nprint(endpoint.id)\n"
      - lang: Python
        label: Together AI SDK (v1)
        source: "from together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nendpoint = client.endpoints.create(\n    model=\"Qwen/Qwen3.5-9B-FP8\",\n    hardware=\"1x_nvidia_a100_80gb_sxm\",\n    min_replicas=2,\n    max_replicas=5,\n)\n\nprint(endpoint.id)\n"
      - lang: TypeScript
        label: Together AI SDK (TypeScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst endpoint = await client.endpoints.create({\n  model: \"Qwen/Qwen3.5-9B-FP8\",\n  hardware: \"1x_nvidia_a100_80gb_sxm\",\n  autoscaling: {\n    max_replicas: 5,\n    min_replicas: 2,\n  }\n});\n\nconsole.log(endpoint.id);\n"
      - lang: JavaScript
        label: Together AI SDK (JavaScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst endpoint = await client.endpoints.create({\n  model: \"Qwen/Qwen3.5-9B-FP8\",\n  hardware: \"1x_nvidia_a100_80gb_sxm\",\n  autoscaling: {\n    max_replicas: 5,\n    min_replicas: 2,\n  }\n});\n\nconsole.log(endpoint.id);\n"
      - lang: Shell
        label: cURL
        source: "curl -X POST \"https://api.together.ai/v1/endpoints\" \\\n     -H \"Authorization: Bearer $TOGETHER_API_KEY\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"model\": \"Qwen/Qwen3.5-9B-FP8\",\n       \"hardware\": \"1x_nvidia_a100_80gb_sxm\",\n       \"autoscaling\": {\n         \"max_replicas\": 5,\n         \"min_replicas\": 2\n       }\n     }'\n"
      operationId: createEndpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEndpointRequest'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DedicatedEndpoint'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
  /endpoints/{endpointId}:
    get:
      tags:
      - Endpoints
      summary: Get endpoint by ID
      description: Retrieves details about a specific endpoint, including its current state, configuration, and scaling settings.
      x-codeSamples:
      - lang: Python
        label: Together AI SDK (v2)
        source: "# Docs for v1 can be found by changing the above selector ^\nfrom together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nendpoint = client.endpoints.retrieve(\"endpoint-id\")\n\nprint(endpoint.id)\n"
      - lang: Python
        label: Together AI SDK (v1)
        source: "from together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nendpoint = client.endpoints.get(\"endpoint-id\")\n\nprint(endpoint.id)\n"
      - lang: TypeScript
        label: Together AI SDK (TypeScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst endpoint = await client.endpoints.retrieve(\"endpoint-id\");\n\nconsole.log(endpoint);\n"
      - lang: JavaScript
        label: Together AI SDK (JavaScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst endpoint = await client.endpoints.retrieve(\"endpoint-id\");\n\nconsole.log(endpoint);\n"
      - lang: Shell
        label: cURL
        source: "curl \"https://api.together.ai/v1/endpoints/endpoint-id\" \\\n     -H \"Authorization: Bearer $TOGETHER_API_KEY\" \\\n     -H \"Content-Type: application/json\"\n"
      operationId: getEndpoint
      parameters:
      - name: endpointId
        in: path
        required: true
        schema:
          type: string
          description: The ID of the endpoint to retrieve
          example: endpoint-d23901de-ef8f-44bf-b3e7-de9c1ca8f2d7
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DedicatedEndpoint'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
    patch:
      tags:
      - Endpoints
      summary: Update endpoint, this can also be used to start or stop a dedicated endpoint
      description: Updates an existing endpoint's configuration. You can modify the display name, autoscaling settings, or change the endpoint's state (start/stop).
      x-codeSamples:
      - lang: Python
        label: Together AI SDK (v2)
        source: "# Docs for v1 can be found by changing the above selector ^\nfrom together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nendpoint = client.endpoints.update(\n    \"endpoint-id\",\n    state=\"STOPPED\"\n)\n\nprint(endpoint)\n"
      - lang: Python
        label: Together AI SDK (v1)
        source: "from together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nendpoint = client.endpoints.update(\n    endpoint_id=\"endpoint-id\",\n    state=\"STOPPED\"\n)\n\nprint(endpoint)\n"
      - lang: TypeScript
        label: Together AI SDK (TypeScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst endpoint = await client.endpoints.update(\"endpoint-id\", {\n  state: \"STOPPED\"\n});\n\nconsole.log(endpoint);\n"
      - lang: JavaScript
        label: Together AI SDK (JavaScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst endpoint = await client.endpoints.update(\"endpoint-id\", {\n  state: \"STOPPED\"\n});\n\nconsole.log(endpoint);\n"
      - lang: Shell
        label: cURL
        source: "curl -X PATCH \"https://api.together.ai/v1/endpoints/endpoint-id\" \\\n     -H \"Authorization: Bearer $TOGETHER_API_KEY\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"state\": \"STOPPED\"\n     }'\n"
      operationId: updateEndpoint
      parameters:
      - name: endpointId
        in: path
        required: true
        schema:
          type: string
          description: The ID of the endpoint to update
          example: endpoint-d23901de-ef8f-44bf-b3e7-de9c1ca8f2d7
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                display_name:
                  type: string
                  description: A human-readable name for the endpoint
                  example: My Llama3 70b endpoint
                state:
                  type: string
                  description: The desired state of the endpoint
                  enum:
                  - STARTED
                  - STOPPED
                  example: STARTED
                autoscaling:
                  $ref: '#/components/schemas/Autoscaling'
                  description: New autoscaling configuration for the endpoint
                inactive_timeout:
                  type: integer
                  description: The number of minutes of inactivity after which the endpoint will be automatically stopped. Set to 0 to disable automatic timeout.
                  nullable: true
                  example: 60
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DedicatedEndpoint'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
    delete:
      tags:
      - Endpoints
      summary: Delete endpoint
      description: Permanently deletes an endpoint. This action cannot be undone.
      x-codeSamples:
      - lang: Python
        label: Together AI SDK (v2)
        source: "# Docs for v1 can be found by changing the above selector ^\nfrom together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nendpoint = client.endpoints.delete(\"endpoint-id\")\n\nprint(endpoint)\n"
      - lang: Python
        label: Together AI SDK (v1)
        source: "from together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nendpoint = client.endpoints.delete(\n    endpoint_id=\"endpoint-id\",\n)\n\nprint(endpoint)\n"
      - lang: TypeScript
        label: Together AI SDK (TypeScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst endpoint = await client.endpoints.delete(\"endpoint-id\");\n\nconsole.log(endpoint);\n"
      - lang: JavaScript
        label: Together AI SDK (JavaScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst endpoint = await client.endpoints.delete(\"endpoint-id\");\n\nconsole.log(endpoint);\n"
      - lang: Shell
        label: cURL
        source: "curl -X \"DELETE\" \"https://api.together.ai/v1/endpoints/endpoint-id\" \\\n     -H \"Authorization: Bearer $TOGETHER_API_KEY\"\n"
      operationId: deleteEndpoint
      parameters:
      - name: endpointId
        in: path
        required: true
        schema:
          type: string
          description: The ID of the endpoint to delete
          example: endpoint-d23901de-ef8f-44bf-b3e7-de9c1ca8f2d7
      responses:
        '204':
          description: No Content - Endpoint successfully deleted
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
  /clusters/availability-zones:
    get:
      tags:
      - Endpoints
      summary: List all available availability zones.
      description: List all available availability zones.
      operationId: availabilityZones
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAvailibilityZonesResponse'
      x-codeSamples:
      - lang: Python
        label: Together AI SDK (v2)
        source: "from together import Together\nimport os\n\nclient = Together(\n    api_key=os.environ.get(\"TOGETHER_API_KEY\"),\n)\n\nresponse = client.endpoints.list_avzones()\n\nprint(response.avzones)\n"
      - lang: TypeScript
        label: Together AI SDK (TypeScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst response = await client.endpoints.listAvzones();\n\nconsole.log(response.avzones);\n"
      - lang: JavaScript
        label: Together AI SDK (JavaScript)
        source: "import Together from \"together-ai\";\n\nconst client = new Together({\n  apiKey: process.env.TOGETHER_API_KEY,\n});\n\nconst response = await client.endpoints.listAvzones();\n\nconsole.log(response.avzones);\n"
      - lang: Shell
        label: cURL
        source: "curl \"https://api.together.ai/v1/clusters/availability-zones\" \\\n     -H \"Authorization: Bearer $TOGETHER_API_KEY\" \\\n     -H \"Content-Type: application/json\"\n"
components:
  schemas:
    DedicatedEndpoint:
      type: object
      description: Details about a dedicated endpoint deployment
      required:
      - object
      - id
      - name
      - display_name
      - model
      - hardware
      - type
      - owner
      - state
      - autoscaling
      - created_at
      properties:
        object:
          description: The object type, which is always `endpoint`.
          const: endpoint
        id:
          type: string
          description: Unique identifier for the endpoint
          example: endpoint-d23901de-ef8f-44bf-b3e7-de9c1ca8f2d7
        name:
          type: string
          description: System name for the endpoint
          example: devuser/deepseek-ai/DeepSeek-R1-a32b82a1
        display_name:
          type: string
          description: Human-readable name for the endpoint
          example: My DeepSeek R1 endpoint
        model:
          type: string
          description: The model deployed on this endpoint
          example: deepseek-ai/DeepSeek-R1
        hardware:
          type: string
          description: The hardware configuration used for this endpoint
          example: 8x_nvidia_h200_140gb_sxm
        type:
          type: string
          enum:
          - dedicated
          description: The type of endpoint
          example: dedicated
        owner:
          type: string
          description: The owner of this endpoint
          example: devuser
        state:
          type: string
          enum:
          - PENDING
          - STARTING
          - STARTED
          - STOPPING
          - STOPPED
          - ERROR
          description: Current state of the endpoint
          example: STARTED
        autoscaling:
          $ref: '#/components/schemas/Autoscaling'
          description: Configuration for automatic scaling of the endpoint
        created_at:
          type: string
          format: date-time
          description: Timestamp when the endpoint was created
          example: 2025-02-04 10:43:55.405000+00:00
    ListEndpoint:
      type: object
      description: Details about an endpoint when listed via the list endpoint
      required:
      - id
      - object
      - name
      - model
      - type
      - owner
      - state
      - created_at
      properties:
        object:
          description: The object type, which is always `endpoint`.
          const: endpoint
        id:
          type: string
          description: Unique identifier for the endpoint
          example: endpoint-d23901de-ef8f-44bf-b3e7-de9c1ca8f2d7
        name:
          type: string
          description: System name for the endpoint
          example: allenai/OLMo-7B
        model:
          type: string
          description: The model deployed on this endpoint
          example: allenai/OLMo-7B
        type:
          type: string
          enum:
          - serverless
          - dedicated
          description: The type of endpoint
          example: serverless
        owner:
          type: string
          description: The owner of this endpoint
          example: together
        state:
          type: string
          enum:
          - PENDING
          - STARTING
          - STARTED
          - STOPPING
          - STOPPED
          - ERROR
          description: Current state of the endpoint
          example: STARTED
        created_at:
          type: string
          format: date-time
          description: Timestamp when the endpoint was created
          example: 2024-02-28 21:34:35.444000+00:00
    Autoscaling:
      type: object
      description: Configuration for automatic scaling of replicas based on demand.
      required:
      - min_replicas
      - max_replicas
      properties:
        min_replicas:
          type: integer
          format: int32
          description: The minimum number of replicas to maintain, even when there is no load
          examples:
          - 2
        max_replicas:
          type: integer
          format: int32
          description: The maximum number of replicas to scale up to under load
          examples:
          - 5
    ErrorData:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              nullable: false
            type:
              type: string
              nullable: false
            param:
              type: string
              nullable: true
              default: null
            code:
              type: string
              nullable: true
              default: null
          required:
          - type
          - message
    CreateEndpointRequest:
      type: object
      required:
      - model
      - hardware
      - autoscaling
      properties:
        display_name:
          type: string
          description: A human-readable name for the endpoint
          example: My Llama3 70b endpoint
        model:
          type: string
          description: The model to deploy on this endpoint
          example: deepseek-ai/DeepSeek-R1
        hardware:
          type: string
          description: The hardware configuration to use for this endpoint
          example: 1x_nvidia_a100_80gb_sxm
        autoscaling:
          $ref: '#/components/schemas/Autoscaling'
          description: Configuration for automatic scaling of the endpoint
        disable_prompt_cache:
          deprecated: true
          type: boolean
          description: This parameter is deprecated and no longer has any effect.
          default: false
        disable_speculative_decoding:
          type: boolean
          description: Whether to disable speculative decoding for this endpoint
          default: false
        state:
          type: string
          description: The desired state of the endpoint
          enum:
          - STARTED
          - STOPPED
          default: STARTED
          example: STARTED
        inactive_timeout:
          type: integer
          description: The number of minutes of inactivity after which the endpoint will be automatically stopped. Set to null, omit or set to 0 to disable automatic timeout.
          nullable: true
          example: 60
        availability_zone:
          type: string
          description: Create the endpoint in a specified availability zone (e.g., us-central-4b)
    ListAvailibilityZonesResponse:
      description: List of unique availability zones
      type: object
      required:
      - avzones
      properties:
        avzones:
          type: array
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      x-bearer-format: bearer
      x-default: default