# Get Started

This short tutorial will teach you the basics of using the Topic Extraction API. It demonstrates how to retrieve a list of topics from a transcript.

## Assumptions

This tutorial assumes that

- You have a Rev AI account. If not, [sign up for a free account](https://www.rev.ai/auth/signup).
- You have a JSON transcript generated from the [Asynchronous Speech-to-Text API](/api/asynchronous). If not, use this [example JSON transcript](https://www.rev.ai/FTC_Sample_1_Transcript.json).


If you have an audio file, you can [generate a JSON transcript](/api/asynchronous/get-started) from it.

## Step 1: Get your access token

The first step is to generate an access token, which will enable access to the Rev AI APIs. Follow these steps:

1. [Log in](https://www.rev.ai/auth/login) to Rev AI.
2. Navigate to the [**Access Token** page](https://www.rev.ai/access-token).
3. Click the **Generate New Access Token** link. Confirm the operation in the pop-up dialog box.


![Creating an access token](/images/create-token.png)

The new access token will be generated and displayed on the screen.

Save your access tokens somewhere safe; you will only be able to see them once. You are allowed a maximum of 2 access tokens at a time.

## Step 2: Submit the transcript for topic extraction

Assuming that your JSON transcript is in a file, submit the transcript to the Topic Extraction API using the command below. Replace the `<REVAI_ACCESS_TOKEN>` placeholder with the access token obtained in [Step 1](#step-1-get-your-access-token) and the `<FILEPATH>` placeholder with the path to the transcript file.


```bash
curl -X POST "https://api.rev.ai/topic_extraction/v1/jobs" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Content-Type: application/json"  \
     -d '{"json":'"$(< <FILEPATH>)"',"metadata":"This is a test"}'
```

You'll receive a response like this:


```bash
{
  "id":"2BRIxqLlaHT1",
  "created_on":"2022-02-01T14:47:03.736Z",
  "metadata":"This is a test",
  "status":"in_progress",
  "type":"topic_extraction"
}
```

The `id` (in this case `2BRIxqLlaHT1`) will enable you to retrieve the list of topics.

## Step 3: Retrieve the list of topics

You now need to wait for the job to complete. Wait for approximately 30 seconds and then check the `status` of your job by querying the API as shown below:


```bash
curl -X GET https://api.rev.ai/topic_extraction/v1/jobs/<ID> \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>"
```

Polling the API periodically for job status is NOT recommended in a production server. Rather, use [webhooks](/api/topic-extraction/webhooks) to asynchronously receive notifications once the topic extraction job completes.

Once the topic extraction job's `status` changes to `completed`, you can retrieve the list of topics in JSON format by running the command below. As before, replace the `<REVAI_ACCESS_TOKEN>` placeholder with the access token obtained in [Step 1](#step-1-get-your-access-token). You must also replace the `<ID>` placeholder with the `id` obtained in [Step 2](#step-2-submit-the-transcript-for-topic-extraction).


```bash
curl -X GET "https://api.rev.ai/topic_extraction/v1/jobs/<ID>/result" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Accept: application/vnd.rev.topic.v1.0+json"
```

Here is an example of the topic extraction output:


```javascript
{
  "topics": [
    {
      ...
    },
    {
      "topic_name": "incredible team",
      "score": 0.9,
      "informants": [
        {
          "content": "We have 17 folks and, uh, I think we have an incredible team and I just want to talk about some things that we've done that I think have helped us get there.",
          "ts": 71.4,
          "end_ts": 78.39
        },
        {
          "content": "Um, it's sort of the overall thesis for this one.",
          "ts": 78.96,
          "end_ts": 81.51
        },
        {
          "content": "One thing that's worth keeping in mind is that recruiting is a lot of work.",
          "ts": 81.51,
          "end_ts": 84
        },
        {
          "content": "Some people think that you can raise money and spend a few weeks building your team and then move on to more",
          "ts": 84.21,
          "end_ts": 88.47
        }
      ]
    },
    {
      ...
    }
  ]
}
```

## Next steps

You should now have a basic idea of how to use the Topic Extraction API. To learn more, read [the API documentation](/api/topic-extraction) for complete details on the different resources and operations available in this API. You can also read about our [other APIs](/api) and find [code samples and SDK documentation](/sdk) that will help you connect your application with the API.