# Acquire a builder token (/en/api-reference/api-ref/speech-to-text/rest-api-v6/acquire)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<CalloutContainer type="warning">
  <CalloutDescription>
    Real-Time STT API versions v5.x and v6.x are deprecated since June 2025 and will reach end-of-life on June 11, 2026. Use the v7 REST API for new projects.
  </CalloutDescription>
</CalloutContainer>

## Endpoint [#endpoint]

* Method: `POST`

* Endpoint: `https://api.agora.io/v1/projects/{appId}/rtsc/speech-to-text/builderTokens`

<CalloutContainer type="info">
  <CalloutDescription>
    Real-Time STT API versions v5.x and v6.x are deprecated since June 2025 and will reach end-of-life on June 11, 2026. This affects your projects as follows:

    * **New projects**: Projects you create starting June 2025 must use v7.0.
    * **Existing projects**: If you're using v5.x or v6.x, migrate to v7.0 before June 11, 2026 to avoid service interruption.
  </CalloutDescription>
</CalloutContainer>

Before starting Real-Time STT conversion, call this endpoint to obtain a `builderToken`. The validity period of a `builderToken` is 5 minutes. After acquiring a token, call the [`start`](start) method within the token validity period to start a Real-Time STT task.

## Request [#request]

### Path parameters [#path-parameters]

**`appId`** Type: `string` Required

The App ID of the project

### Request body [#request-body]

`APPLICATION/JSON`

#### BODY [#body]

**`instanceId`** Type: `string` Required

User-defined string identifier. Must be no more than 64 characters and can include:

* All lowercase English letters (a-z)
* All capital letters (A-Z)
* Numbers 0-9
* `-`, `_`

You can generate multiple builder tokens using an `instanceId`, but only one token can be used to initiate a task.

## Response [#response]

* If the returned status code is `200`, the request was successful. The response body contains the result of the request.

  #### OK [#ok]

**`createTs`** Type: `integer`

Unix timestamp (seconds) when the `builderToken` was generated.

**`instanceId`** Type: `string`

The `instanceId` you specified in the request.

**`tokenName`** Type: `string`

The value of the `builderToken` you use to call other methods.

* If the returned status code is not `200`, the request failed. Refer to `message` field to understand the possible reasons for failure.

#### Non-200 [#non-200]

**`message`** Type: `string`

The reason why the request failed.

## Authorization [#authorization]

This endpoint requires [Basic Auth](../authentication).

## Request example [#request-example]

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="python">
      Python
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="nodejs">
      Node.js
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
          curl --request POST \
            --url https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/builderTokens \
            --header 'Authorization: Basic <credentials>' \
            --header 'Content-Type: <string>' \
            --data '
          {
            "instanceId": "User-defined instance ID"
          }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="python">
    ```python
        import requests

        url = "https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/builderTokens"

        payload = { "instanceId": "User-defined instance ID" }
        headers = {
            "Authorization": "Basic <credentials>",
            "Content-Type": "<string>"
        }

        response = requests.request("POST", url, json=payload, headers=headers)

        print(response.text)
    ```
  </CodeBlockTab>

  <CodeBlockTab value="nodejs">
    ```js
        const url = 'https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/builderTokens';
        const options = {
          method: 'POST',
          headers: {Authorization: 'Basic <credentials>', 'Content-Type': '<string>'},
          body: JSON.stringify({instanceId: 'User-defined instance ID'})
        };

        fetch(url, options)
          .then(res => res.json())
          .then(json => console.log(json))
          .catch(err => console.error(err));
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Response example [#response-example]

### 200 [#200]

```json
    {
      "createTs": 1678505791,
      "instanceId": "XXXX",
      "tokenName": "tokenName of the transcription task"
    }
```

### Non-200 [#non-200-1]

```json
    {
      "message": "The reason why the request failed.",
    }
```