> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criando novas tasks

Dentro do seu Workstation App você pode criar tasks e revisar seus outputs para garantir que os resultados estão corretos.

## Creating tasks via API

Criar uma nova task é similar a fazer uma chamada para um Canvas, no lugar de passar um `canvas_id`, você deve passar o seu `application_id`.

Vá até a página do seu Workstation App e siga estes passos:

<Steps>
  <Step title="Open Connect via API">
    Na barra do topo, clique no botão com três pontinhos do lado direito do título do seu app e selecione "Connect via API".

    <img class="rounded-2xl" src="https://mintcdn.com/meistrari/pblu7JGV78zF0-_0/images/guides/workstation/connect-app-dropdown.png?fit=max&auto=format&n=pblu7JGV78zF0-_0&q=85&s=dbf98bcf941c086754941dc595e20a23" alt="Connect via API" width="858" height="502" data-path="images/guides/workstation/connect-app-dropdown.png" />
  </Step>

  <Step title="Get your app data">
    Aqui você vai encontrar toda a informação necessária para começar a criar novas task via API. Escolha a sua linguagem de preferência e use um dos snippets de código pra começar a integrar!

    <img class="rounded-2xl" src="https://mintcdn.com/meistrari/pblu7JGV78zF0-_0/images/guides/workstation/connect-app-modal.png?fit=max&auto=format&n=pblu7JGV78zF0-_0&q=85&s=c8f76787abcaf827860ca56ee0bce586" alt="Connect modal" width="1308" height="1380" data-path="images/guides/workstation/connect-app-modal.png" />
  </Step>
</Steps>

Por padrão, todas as tasks são criadas como se fossem completions assíncronas. Você receberá uma resposta com o status de `success` e a task criada terá o status de `running`. Você tem duas opções para consumir o resultado de uma task:

* Polling durante a execução
* Utilizar uma webhook URL

### Polling de tasks durante a execução

Você pode realizar um polling simples de uma task até que seu status mude para `completed` ou `failed`. Para obter o status de uma task depois de criá-la podemos enviar um request para o endpoitn `/task` da API.

<CodeGroup>
  ```typescript TypeScript Tela SDK theme={null}
  let task = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
      applicationId: process.env.TELA_APPLICATION_ID,
      variables: {
          document: tela.createFile('https://example.com/document.pdf')
      },
  })

  let isTaskCompleted = false

  while (!isTaskCompleted) {
      const response = await fetch(`https://api.tela.com/task/${task.id}`)
      task = await response.json()
      isTaskCompleted = task.status === 'completed' || task.status === 'failed'
  }
  ```

  ```javascript JavaScript Tela SDK theme={null}
  let task = await tela.completions.create({
      applicationId: process.env.TELA_APPLICATION_ID,
      variables: {
          document: tela.createFile('https://example.com/document.pdf')
      },
  })

  let isTaskCompleted = false

  while (!isTaskCompleted) {
      const response = await fetch(`https://api.tela.com/task/${task.id}`)
      task = await response.json()
      isTaskCompleted = task.status === 'completed' || task.status === 'failed'
  }
  ```

  ```python Python Tela SDK theme={null}
  task = tela.completions.create(
      application_id=os.getenv('TELA_APPLICATION_ID'),
      variables={
          "document": tela.create_file("https://example.com/document.pdf")
      }
  )

  is_task_completed = False

  while not is_task_completed:
      response = requests.get(f'https://api.tela.com/task/{task.id}')
      task = response.json()
      is_task_completed = task.status in ['completed', 'failed']
  ```
</CodeGroup>

### Utilizando uma webhook URL

Você pode passar uma `webhook_url` na sua chamada de API. Desse forma o endpoit que você passou vai receber um `POST` request quando a execução da task terminar.

#### Estrutura da Resposta do Webhook

Quando uma task é concluída, seu endpoint de webhook receberá uma requisição POST com a seguinte estrutura:

```json theme={null}
{
  "id": "b83b1558-de5b-4e45-b517-7bececbdd154",
  "status": "succeeded",
  "input_content": {
    "variables": {
      "document": {
        "file_url": "https://example.com/document.pdf"
      }
    },
    "messages": []
  },
  "output_content": {
    "role": "assistant",
    "structured_content": false,
    "content": {
      "fileSummary": "Este documento contém relatórios financeiros trimestrais mostrando um aumento de 15% na receita em comparação com o último trimestre, com destaques em melhorias de eficiência operacional e expansão de mercado na região APAC."
    }
  },
  "raw_input": {
    "application_id": "95cec438-6080-44fe-8275-28b16bd40178",
    "variables": {
      "document": {
        "file_url": "https://example.com/document.pdf"
      }
    },
    "webhook_url": "https://example.com/webhook"
  },
  "raw_output": {
    "fileSummary": "Este documento contém relatórios financeiros trimestrais mostrando um aumento de 15% na receita em comparação com o último trimestre, com destaques em melhorias de eficiência operacional e expansão de mercado na região APAC."
  },
  "compatibility_date": "2024-10-14",
  "prompt_version_id": "76065caa-c519-441a-8fe2-cc43e29664ab",
  "prompt_application_id": "95cec438-6080-44fe-8275-28b16bd40178",
  "workspace_id": "3f55cfd9-4427-4887-a181-d9ad39967802",
  "created_at": "2024-10-14T19:00:53.664Z",
  "updated_at": "2024-10-14T19:01:15.892Z"
}
```

Campos principais na resposta do webhook:

* `status`: Pode ser "created", "running", "succeeded" ou "failed"
* `input_content`: Contém as variáveis e mensagens enviadas na requisição
* `output_content`: Contém a saída estruturada do seu Canvas, correspondendo ao schema de saída definido
* `raw_output`: Os dados de saída brutos no formato definido pelos outputs do seu Canvas

<CodeGroup>
  ```typescript Typescript Tela SDK theme={null}
  const task = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
      applicationId: process.env.TELA_APPLICATION_ID,
      variables: {
          document: tela.createFile('https://example.com/document.pdf')
      },
      webhook_url: "https://example.com/webhook"
  })
  ```

  ```javascript Javascript Tela SDK theme={null}
  const task = await tela.completions.create({
      applicationId: process.env.TELA_APPLICATION_ID,
      variables: {
          document: tela.createFile('https://example.com/document.pdf')
      },
      webhook_url: "https://example.com/webhook"
  })
  ```

  ```python Python Tela SDK theme={null}
  task = tela.completions.create(
      application_id=os.getenv('TELA_APPLICATION_ID'),
      variables={
          "document": tela.create_file("https://example.com/document.pdf")
      }
      webhook_url="https://example.com/webhook"
  )
  ```

  ```sh cURL theme={null}
  curl -XPOST https://api.tela.com/v2/chat/completions \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer $TELA_API_KEY' \
      -d '{
          "application_id": "'$TELA_APPLICATION_ID'",
          "variables": {
              "document": {
                  "file_url": "https://example.com/document.pdf"
              }
          },
          "webhook_url": "https://example.com/webhook"
      }'
  ```
</CodeGroup>

## Listando tasks

Para listar as tasks de um app você pode enviar um `GET` request pro endpoint `/task`. Esse endpoint suporta alguns parâmetros opicionais para filtrar e paginar seus resultados:

### Parâmetros de paginação

* `limit`: Número de resultados por resposta (padrão: 10, intervalo: 1-100)
* `offset`: Posição inicial dos resultados (padrão: 0)

### Filtering parameters

* `status`: Array de status de tasks (opções: "created", "running", "validating", "completed", "failed")
* `since`: Data inicial para filtrar as tasks (formato: timestamp ou ISO 8601)
* `until`: Data final para filtar as tasks (formato: timestamp ou ISO 8601)
* `approvedBy`: Email do usuário que aprovou a task
* `revisionProcess`: Tipo de revisão recebida (opções: "approvedWithRevisions", "approvedDirectly")
* `promptApplicationId`: ID da aplicação onde a task foi criada
* `promptVersionId`: ID da versão do Canvas utilizada para criar a task
* `ids`: Array de IDs específicos de tasks para serem listadas

### Sorting parameters

* `orderBy`: Campo para ordenar por (opções: "name", "reference", "approvedAt", "createdAt", "updatedAt", "id", "status", "approvedBy", "createdBy")
* `order`: Sentido de ordenação  (opções: "asc" or "desc")

### Example request

Aqui está o exemplo de um request listando 50 tasks com o status "completed" criadas depois do dia 1 de Novembro de 2024, ordenas em ordem crescente pelo nome:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const url = new URL('https://api.tela.com/task')
  url.searchParams.append('limit', '50')
  url.searchParams.append('promptApplicationId', '{YOUR_APPLICATION_ID}')
  url.searchParams.append('status', JSON.stringify(['completed']))
  url.searchParams.append('since', '2024-11-01T00:00:00Z')
  url.searchParams.append('orderBy', 'name')
  url.searchParams.append('order', 'asc')

  const response = await fetch(url, {
      method: 'GET',
      headers: {
          'Authorization': `Bearer ${process.env.TELA_API_KEY}`,
          'Content-Type': 'application/json',
      },
  });

  const tasks = await response.json()
  ```

  ```python Python theme={null}
  import requests
  import os

  response = requests.get(
      'https://api.tela.com/task',
      headers={
          'Authorization': f'Bearer {os.getenv("TELA_API_KEY")}',
          'Content-Type': 'application/json',
      },
      params={
          'limit': 50,
          'promptApplicationId': os.getenv('TELA_APPLICATION_ID'),
          'status': '["completed"]',
          'since': '2024-11-01T00:00:00Z',
          'orderBy': 'name',
          'order': 'asc',
      }
  )

  tasks = response.json()
  ```

  ```sh cURL theme={null}
  curl -X GET "https://api.tela.com/task?limit=50&promptApplicationId=$TELA_APPLICATION_ID&status=%5B%22completed%22%5D&since=2024-11-01T00%3A00%3A00Z&orderBy=name&order=asc" \
    -H "Authorization: Bearer $TELA_API_KEY" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>