> ## Documentation Index
> Fetch the complete documentation index at: https://portkey-docs-mintlify-add-terraform-provider-docs-72855.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Completions

> Execute your saved prompt templates on Portkey


Portkey Prompts API completely <Tooltip tip="Chat Completions or Completions">follows OpenAI's format</Tooltip>  for both *requests* and *responses*, making it a drop-in replacement existing for your existing **[Chat](/api-reference/inference-api/chat)** or **[Completions](/api-reference/inference-api/completions)** calls.

# Features

<AccordionGroup>
  <Accordion icon="input-pipe" title="Send Variables">
    Create your Propmt Template on [Portkey UI](/product/prompt-library/prompt-templates), define variables, and pass them with this API:

    <Tabs>
      <Tab title="String Variables">
        <CodeGroup>
          ```sh cURL theme={null}
          curl -X POST "https://api.portkey.ai/v1/prompts/YOUR_PROMPT_ID/completions" \
            -H "Content-Type: application/json" \
            -H "x-portkey-api-key: $PORTKEY_API_KEY" \
            -d '{
              "variables": {
                "joke_topic": "elections",
                "humor_level": "10"
              }
            }'
          ```

          ```py Python theme={null}
          from portkey_ai import Portkey

          client = Portkey(
              api_key="PORTKEY_API_KEY"
          )

          completion = client.prompts.completions.create(
              prompt_id="YOUR_PROMPT_ID",
              variables={
                  "joke_topic": "elections",
                  "humor_level": "10"
              }
          )
          ```

          ```js JavaScript theme={null}
          import Portkey from 'portkey-ai';

          const portkey = new Portkey({
            apiKey: 'PORTKEY_API_KEY'
          });

          const completion = await portkey.prompts.completions.create({
            promptId: "YOUR_PROMPT_ID",
            variables: {
              "joke_topic": "elections",
              "humor_level": "10"
            }
          });
          ```
        </CodeGroup>
      </Tab>

      <Tab title="JSON Variables">
        <Note>
          When passing JSON data with variables, `stringify` the value before sending.
        </Note>

        <CodeGroup>
          ```sh cURL theme={null}
          curl -X POST "https://api.portkey.ai/v1/prompts/YOUR_PROMPT_ID/completions" \
            -H "Content-Type: application/json" \
            -H "x-portkey-api-key: $PORTKEY_API_KEY" \
            -d '{
              "variables": {
                "user_data": "{\"name\":\"John\",\"preferences\":{\"topic\":\"AI\",\"format\":\"brief\"}}"
              }
            }'
          ```

          ```python Python theme={null}
          import json

          user_data = json.dumps({
              "name": "John",
              "preferences": {
                  "topic": "AI",
                  "format": "brief"
              }
          })

          completion = client.prompts.completions.create(
              prompt_id="YOUR_PROMPT_ID",
              variables={
                  "user_data": user_data
              }
          )
          ```

          ```javascript JavaScript theme={null}
          const userData = JSON.stringify({
            name: "John",
            preferences: {
              topic: "AI",
              format: "brief"
            }
          });

          const completion = await portkey.prompts.completions.create({
            promptId: "YOUR_PROMPT_ID",
            variables: {
              user_data: userData
            }
          });
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion icon="pen-to-square" title="Override Prompt Settings">
    You can override any model hyperparameter saved in the prompt template by sending its new value at the time of making a request:

    <CodeGroup>
      ```sh cURL theme={null}
      curl -X POST "https://api.portkey.ai/v1/prompts/YOUR_PROMPT_ID/completions" \
        -H "Content-Type: application/json" \
        -H "x-portkey-api-key: $PORTKEY_API_KEY" \
        -d '{
          "variables": {
            "user_input": "Hello world"
          },
          "temperature": 0.7,
          "max_tokens": 250,
          "presence_penalty": 0.2
        }'
      ```

      ```python Python theme={null}
      completion = client.prompts.completions.create(
          prompt_id="YOUR_PROMPT_ID",
          variables={
              "user_input": "Hello world"
          },
          temperature=0.7,
          max_tokens=250,
          presence_penalty=0.2
      )
      ```

      ```javascript JavaScript theme={null}
      const completion = await portkey.prompts.completions.create({
        promptId: "YOUR_PROMPT_ID",
        variables: {
          user_input: "Hello world"
        },
        temperature: 0.7,
        max_tokens: 250,
        presence_penalty: 0.2
      });
      ```
    </CodeGroup>
  </Accordion>

  <Accordion icon="code-compare" title="Call Specific Prompt Version">
    Passing the `{promptId}` always calls the `Published` version of your prompt.

    But, you can also call a specific template version by appending its version number, like `{promptId@12}`:

    **Version Tags**:

    * `@latest`: Calls the <Tooltip tip="May not be the same as the Published version">most recent version</Tooltip>
    * `@{NUMBER}` (like `@12`): Calls the specified version number
    * `No Suffix`: Here, Portkey defaults to the `Published` version

    <CodeGroup>
      ```curl cURL {1} theme={null}
      curl -X POST "https://api.portkey.ai/v1/prompts/PROMPT_ID@12/completions" \
        -H "Content-Type: application/json" \
        -H "x-portkey-api-key: $PORTKEY_API_KEY" \
        -d '{
          "variables": {
            "user_input": "Hello world"
          }
        }'
      ```

      ```python Python {2} theme={null}
      completion = client.prompts.completions.create(
          prompt_id="PROMPT_ID@12", # PROMPT_ID@latest will call the latest version
          variables={
              "user_input": "Hello world"
          }
      )
      ```

      ```javascript JavaScript {2} theme={null}
      const completion = await portkey.prompts.completions.create({
        promptId: "PROMPT_ID@12", // PROMPT_ID@latest will call the latest version
        variables: {
          user_input: "Hello world"
        }
      });
      ```
    </CodeGroup>
  </Accordion>

  <Accordion icon="water" title="Streaming">
    Prompts API also supports streaming responses, and completely follows the OpenAI schema.

    * Set `stream:True` explicitly in your request to enable streaming

    <CodeGroup>
      ```sh cURL {8} theme={null}
      curl -X POST "https://api.portkey.ai/v1/prompts/YOUR_PROMPT_ID/completions" \
        -H "Content-Type: application/json" \
        -H "x-portkey-api-key: $PORTKEY_API_KEY" \
        -d '{
          "variables": {
            "user_input": "Hello world"
          },
          "stream": true
          "max_tokens": 250,
          "presence_penalty": 0.2
        }'
      ```

      ```python Python {4} theme={null}
      completion = client.prompts.completions.create(
          prompt_id="YOUR_PROMPT_ID",
          variables={"user_input": "Hello"},
          stream=True
      )

      for chunk in completion:
          print(chunk.choices[0].delta)
      ```

      ```javascript JavaScript {6} theme={null}
      const completion = await portkey.prompts.completions.create({
        promptId: "YOUR_PROMPT_ID",
        variables: {
          user_input: "Hello"
        },
        stream: true
      });

      for await (const chunk of completion) {
        console.log(chunk.choices[0].delta.content);
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>