API de proyectos

Un proyecto agrupa tus conversaciones, datasets, entrenamientos y adapters. Cada proyecto pertenece a tu organización.

Rutas

Todas aceptan API Key.

GET/api/v1/projects

Lista tus proyectos

POST/api/v1/projects

Crea un proyecto

GET/api/v1/projects/{projectId}

Detalle de un proyecto

PATCH/api/v1/projects/{projectId}

Actualiza campos

DELETE/api/v1/projects/{projectId}

Archiva el proyecto

Listar proyectos

bash

curl "https://app.astrapp.lat/api/v1/projects?status=active&per_page=20" \
  -H "Authorization: Bearer $ASTRAPP_API_KEY"

Parámetro	Descripción
`page`	Página, desde 1. Por defecto 1.
`per_page`	Resultados por página, de 1 a 100. Por defecto 20.
`status`	draft, active, training, completed o archived.
`archetype`	Filtra por arquetipo.
`sort`	Campo para ordenar; antepón - para orden descendente. Por defecto, los más nuevos primero.

Cada proyecto del listado trae además counts: cuántas conversaciones, datasets, entrenamientos y adapters tiene. El detalle de un proyecto no lo incluye. El ejemplo muestra solo los campos principales de cada proyecto.

json

{
  "success": true,
  "data": [
    {
      "id": "3f1a9c2e-5b74-4d81-9e02-7c6a1b4f8d35",
      "name": "Bot de ventas",
      "description": "Asistente para calificar leads",
      "archetype": "llm",
      "status": "active",
      "version": 1,
      "organization_id": "0b6e2d4a-8c1f-4e3a-9d7b-5a2c1e8f6d40",
      "created_by": "7c9e1b2d-3f4a-4b5c-8d6e-1a2b3c4d5e6f",
      "created_at": "2026-09-22T10:00:00.000Z",
      "updated_at": "2026-09-22T10:00:00.000Z",
      "counts": {
        "conversations": 172,
        "datasets": 2,
        "training_jobs": 1,
        "adapters": 1
      }
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

Crear un proyecto

bash

curl -X POST https://app.astrapp.lat/api/v1/projects \
  -H "Authorization: Bearer $ASTRAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bot de ventas",
    "archetype": "llm",
    "description": "Asistente para calificar leads"
  }'

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del proyecto, de 2 a 255 caracteres.
`archetype`	string	Sí	classification, regression, nlp, llm, cv o custom.
`description`	string	No	Hasta 1,000 caracteres.
`objective`	string	No	Objetivo del proyecto, hasta 500 caracteres.
`success_criteria`	string	No	Criterio de éxito, hasta 500 caracteres.
`tags`	string[]	No	Hasta 10 etiquetas.
`archetype_config`	object	No	Configuración libre del arquetipo.

Responde 201 con el proyecto en data. Todo proyecto nuevo nace con status: "active" y version: 1.

Para modelos de chat, usa llm

El arquetipo es obligatorio. Los proyectos que crea la app usan llm, el que corresponde a entrenar un modelo de lenguaje.

Obtener un proyecto

bash

curl https://app.astrapp.lat/api/v1/projects/$PROJECT_ID \
  -H "Authorization: Bearer $ASTRAPP_API_KEY"

Responde { "success": true, "data": { … } }. Con ?expand=organization el proyecto trae también el id y el nombre de su organización. Un id que no existe o que es de otra organización responde 404.

Actualizar un proyecto

bash

curl -X PATCH https://app.astrapp.lat/api/v1/projects/$PROJECT_ID \
  -H "Authorization: Bearer $ASTRAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bot de ventas v2",
    "status": "completed"
  }'

Acepta los mismos campos que la creación, todos opcionales, más status (draft, active, training, completed o archived). Responde el proyecto actualizado.

Archivar un proyecto

bash

curl -X DELETE https://app.astrapp.lat/api/v1/projects/$PROJECT_ID \
  -H "Authorization: Bearer $ASTRAPP_API_KEY"

DELETE no borra nada: cambia el estado del proyecto a archived, guarda la fecha en archived_at y responde 204 sin cuerpo. Sus datasets, entrenamientos y adapters se conservan. Para reactivarlo, manda un PATCH con status: "active".

Errores frecuentes

Estado	Código	Causa
400	`VALIDATION_ERROR`	Falta un campo requerido o un valor no es válido; details dice cuál.
400	`VALIDATION_ERROR`	El projectId de la ruta no es un UUID.
404	`NOT_FOUND`	El proyecto no existe o no es de tu organización.