Proyectos

📁 Proyectos

Un proyecto es el contenedor al que pertenecen todos los archivos y todos los análisis. Su ID numérico es el único dato que el resto de esta referencia da por supuesto: project al subir un archivo, project_id en todos los endpoints de lectura del call center.

Hay dos formas de obtenerlo:

Desde la API — GET /api/projects/ lista todos los proyectos visibles para tu clave, con su ID.
Desde la aplicación web — consulta Encontrar el ID en la aplicación web más abajo.

Todos los endpoints de esta página requieren una sesión de navegador o una clave API — consulta Autenticación.

GET /api/projects/

Lista los proyectos visibles para quien llama, del más reciente al más antiguo.

Autenticación: clave API o sesión.

Parámetros de consulta:

Parámetro	Obligatorio	Descripción
`project_type`	no	Filtra por tipo: `audio` o `survey`. Los proyectos de call center y los de entrevistas son ambos `audio` — se distinguen por `audio_type`.
`team`	no	Limita el resultado a los proyectos de un equipo, por ID de equipo. Se ignora en silencio si el equipo no existe o si el usuario de la clave no es miembro de él — recibirás la lista completa sin filtrar, no un error, así que revisa el campo `team` de los resultados si te importa.

Respuesta (200 OK):

Los resultados están paginados, 100 por página. Sigue next si tienes más proyectos que eso.

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 312,
      "name": "Ventas — junio",
      "project_type": "audio",
      "description": "",
      "status": "created",
      "user": 87,
      "team": 4,
      "created_at": "2026-06-01T09:14:52Z",
      "updated_at": "2026-06-28T17:31:06Z",
      "audio_type": "call",
      "return_timestamps": false,
      "default_language": "es",
      "metadata": null,
      "shared_with": [91, 104],
      "survey_template": null,
      "evaluation_rubric": 7,
      "predefined_codes": null,
      "auto_analysis_enabled": true,
      "auto_analysis_types": ["calls_analysis_copc"],
      "auto_analysis_questions": null,
      "auto_analysis_batch_size": 20,
      "auto_analysis_max_wait_seconds": 300,
      "analyzed_custom_question_calls": 0
    },
    { "…": "un objeto por proyecto" }
  ]
}

Los campos que realmente vas a usar:

Campo	Descripción
`id`	Lo que pasas como `project` o `project_id` en todos los demás endpoints.
`name`	El nombre que aparece en el selector de proyectos de la aplicación web.
`project_type`	`audio` (grabaciones) o `survey` (respuestas de encuestas).
`audio_type`	`call`, `interview` o `focus_group`. Las funciones de call center solo aplican a los proyectos `call`.
`status`	`created`, `processing`, `completed` o `failed`. Los proyectos eliminados nunca se devuelven.
`team`	El ID del equipo propietario, o `null` si el proyecto pertenece a un usuario.
`auto_analysis_enabled`	Si las llamadas se analizan automáticamente según llegan. Consulta Subir Llamadas para Análisis.
`shared_with`	IDs de los usuarios con los que se ha compartido el proyecto explícitamente.

Un campo a tener en cuenta: metadata es un objeto JSON libre y, en los proyectos de llamadas, guarda además las filas del manifiesto CSV que todavía no han encontrado su archivo — así que puede ser muy grande. Ignóralo salvo que seas tú quien haya guardado algo ahí.

Qué proyectos se devuelven: los tuyos, todos los de los equipos donde eres administrador y cualquiera que se haya compartido contigo explícitamente. Los proyectos eliminados quedan excluidos. Una clave hereda exactamente la visibilidad de su usuario — consulta Alcance.

Ejemplo — lista tus proyectos de call center:

audio_type no es un filtro del servidor, así que pide project_type=audio y filtra los resultados.

curl -sS "https://app.uspeech.io/api/projects/?project_type=audio" \
  -H "Authorization: Api-Key $USPEECH_KEY" \
  | jq -r '.results[] | select(.audio_type == "call") | "\(.id)\t\(.name)"'

import os

import requests

BASE_URL = "https://app.uspeech.io"
HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}

response = requests.get(
    f"{BASE_URL}/api/projects/",
    headers=HEADERS,
    params={"project_type": "audio"},
    timeout=30,
)
response.raise_for_status()

for project in response.json()["results"]:
    if project["audio_type"] == "call":
        print(project["id"], project["name"])

const BASE_URL = 'https://app.uspeech.io';
const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };

const response = await fetch(`${BASE_URL}/api/projects/?project_type=audio`, { headers: HEADERS });
if (!response.ok) throw new Error(await response.text());

const { results } = await response.json();
for (const project of results.filter((p) => p.audio_type === 'call')) {
  console.log(project.id, project.name);
}

💡 Consejo: consulta el ID una vez y guárdalo en la configuración de tu integración. Los IDs de proyecto son estables — no cambian durante toda la vida del proyecto.

GET /api/projects/{id}/

Consulta un proyecto concreto. Devuelve el mismo objeto que una entrada de la lista anterior.

Autenticación: clave API o sesión.

Útil para confirmar que un proyecto es de llamadas (audio_type) y comprobar si el análisis automático está activado antes de empezar a subir archivos.

curl -sS https://app.uspeech.io/api/projects/312/ \
  -H "Authorization: Api-Key $USPEECH_KEY"

import os

import requests

BASE_URL = "https://app.uspeech.io"
HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}
project_id = 312

response = requests.get(f"{BASE_URL}/api/projects/{project_id}/", headers=HEADERS, timeout=30)
response.raise_for_status()
project = response.json()

print(project["name"], project["audio_type"], project["auto_analysis_enabled"])

const BASE_URL = 'https://app.uspeech.io';
const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };
const projectId = 312;

const response = await fetch(`${BASE_URL}/api/projects/${projectId}/`, { headers: HEADERS });
if (!response.ok) throw new Error(await response.text());
const project = await response.json();

console.log(project.name, project.audio_type, project.auto_analysis_enabled);

Un 404 Not Found aquí significa que el proyecto existe pero no es visible para el usuario de la clave — comprueba que ese usuario sea el propietario, administre su equipo o lo tenga compartido.

Para cambiar la configuración de análisis automático de un proyecto, usa PATCH /api/projects/{id}/; los campos configurables y sus reglas de validación están documentados en Subir Llamadas para Análisis.

Encontrar el ID en la aplicación web

Si prefieres leer el ID en pantalla en lugar de llamar a la API:

Abre Conversaciones en la aplicación web.
Elige el proyecto en el selector de la parte superior de la página.
El ID aparece en la tarjeta Subir archivos, junto al enlace Subir mediante API.

Los proyectos que creas mediante POST /api/projects/ devuelven su nuevo id en la respuesta 201 Created, así que en ese caso no hace falta consultarlo.

Dónde se usa el ID

Transcripción — project en POST /api/files/
Subir Llamadas para Análisis — todo el recorrido
Metadatos de llamadas — POST /api/projects/{id}/call-manifest/
Informes de llamadas — project_id en todos los endpoints de informes