# Acquire a builder token (/en/api-reference/api-ref/speech-to-text/rest-api-v5/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]

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

The value of the builder token you use to call other methods.

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

Unix timestamp (seconds) when the builder token was generated.

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

The `instanceId` you specified in the request.

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

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

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

The reason why the request failed.

**`code`** Type: `integer`

The error code.

## 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>'     
    ```
  </CodeBlockTab>

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

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

        headers = {"Authorization": "Basic <credentials>"}

        response = requests.request("POST", url, 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>'}};

        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
    {
      "tokenName": "The value of the builder token you use to call other methods.",
      "createTs": null,
      "instanceId": "The `instanceId` you specified in the request."
    }
```

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

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