Documentación de la API de Projekt Republic

La API de Projekt Republic es REST, habla JSON y es multi-tenant: cada recurso pertenece a una organización. Todo el dominio del producto vive bajo el prefijo de versión /api/v1; /health y /ready quedan fuera (son de infraestructura, no de producto).

Contract-first: el contrato se declara en el backend y se materializa como un documento OpenAPI; ese documento alimenta la referencia interactiva de esta página y los SDKs generados. Ningún endpoint existe si no está en el contrato.

1. Consigue un token. Un owner o admin de la organización crea un Personal Access Token en Ajustes → API keys. El token (pjk_live_…) se muestra una sola vez: cópialo y guárdalo en un gestor de secretos.

2. Haz tu primera llamada. Envía el token en la cabecera Authorization. Por ejemplo, para leer tu propio perfil:

curl https://projekt.3xa.es/api/v1/me \
  -H "Authorization: Bearer pjk_live_xxxxxxxxxxxxxxxxxxxx"

3. Recorre tus organizaciones. La mayoría de recursos cuelgan de una organización ({org_id} en la ruta). Lista los proyectos de una:

curl https://projekt.3xa.es/api/v1/organizations/{org_id}/projects \
  -H "Authorization: Bearer pjk_live_xxxxxxxxxxxxxxxxxxxx"

Todas las respuestas incluyen la cabecera X-Request-ID, útil para correlacionar con soporte si algo falla.

La API se autentica con Personal Access Tokens (PAT) de tipo bearer. La sesión del navegador usa cookies HttpOnly; los PATs son el mecanismo para scripts, SDKs e integraciones automatizadas.

Authorization: Bearer pjk_live_xxxxxxxxxxxxxxxxxxxx

Toda respuesta no-2xx usa el mismo envelope. El campo request_id coincide con la cabecera X-Request-ID y ayuda a rastrear el fallo en los logs.

{
  "error": {
    "code": "not_found",
    "message": "Resource not found",
    "request_id": "b3f1c2a4-..."
  }
}

Los errores de validación de entrada devuelven 422 con code: "validation_error"; el message enumera los campos inválidos en formato campo: motivo:

{
  "error": {
    "code": "validation_error",
    "message": "body.email: value is not a valid email address; body.name: field required",
    "request_id": "b3f1c2a4-..."
  }
}

Los endpoints sensibles —principalmente los de autenticación— están limitados por IP de origen y por cuenta mediante una ventana fija. Al superar el cupo, la API responde 429 con el envelope estándar (code: "too_many_requests").

El límite es fail-open: si el backend de límites no está disponible, la petición no se bloquea — prevalece la disponibilidad. Diseña tus clientes para reintentar con backoff exponencial ante un 429 y evita ráfagas innecesarias.

De cero a integrado en tres pasos: emite una key, llama al API con ella y, si trabajas con un asistente, engánchalo por MCP. Cada paso enlaza a la sección con el detalle completo.

El catálogo completo de endpoints, esquemas, parámetros y respuestas se renderiza a continuación directamente desde el contrato OpenAPI en vivo. Cada operación muestra el candado de autenticación (bearer PAT) que exige la API. No existe ninguna lista manual que pueda quedarse obsoleta: el contrato es la documentación.

La forma más rápida de darle Projekt Republic a tu asistente: un servidor MCP remoto ya alojado. Una única URL a la que Claude —o cualquier cliente Model Context Protocol— se conecta por Streamable HTTP. No hay nada que instalar ni alojar: al conectar se abre un flujo OAuth con tu cuenta de Projekt Republic y el acceso queda ligado a tus permisos reales.

claude.ai (web / desktop)

1. Abre Ajustes → Conectores.
2. Pulsa «Añadir conector personalizado» y pega la URL https://projekt.3xa.es/mcp.
3. Al conectar se abre el login OAuth: entra con tu cuenta Projekt Republic y pulsa Permitir.

Claude Code

claude mcp add --transport http projekt https://projekt.3xa.es/mcp

Claude Desktop y cualquier cliente MCP

Cualquier cliente compatible con MCP sobre Streamable HTTP solo necesita la URL. En una configuración JSON (p. ej. claude_desktop_config.json o .mcp.json):

{
  "mcpServers": {
    "projekt": {
      "type": "http",
      "url": "https://projekt.3xa.es/mcp"
    }
  }
}

Si tu cliente no soporta el flujo OAuth, usa un PAT como alternativa: añade "headers": { "Authorization": "Bearer pjk_live_…" } a esa entrada (cómo crear el token, en Autenticación).

Qué puede hacer

El Projekt Republic MCP Server expone la API REST como un servidor Model Context Protocol (MCP), el protocolo estándar para que un LLM lea y mute datos de herramientas externas de forma segura. Claude Desktop, Claude Code y cualquier cliente MCP compatible pueden conectarse a él con un pjk_live_… PAT y empezar a trabajar sobre proyectos, tareas y miembros del equipo sin procesar HTML ni scrapers.

Variables de entorno

Configuración del cliente (Claude Desktop / Claude Code)

Añade esta entrada a tu claude_desktop_config.json (Claude Desktop) o a tu .mcp.json (Claude Code) apuntando al servidor compilado:

{
  "mcpServers": {
    "projekt": {
      "command": "node",
      "args": ["/RUTA/ABSOLUTA/apps/mcp/dist/index.js"],
      "env": {
        "PROJEKT_API_TOKEN": "pjk_live_tu_token",
        "PROJEKT_API_URL": "https://projekt.3xa.es/api/v1",
        "PROJEKT_ORG_ID": "tu-uuid-de-org"
      }
    }
  }
}

Alternativamente, desde la raíz del repositorio con Claude Code CLI:

claude mcp add projekt \
  --env PROJEKT_API_TOKEN=pjk_live_tu_token \
  -- node "$(pwd)/apps/mcp/dist/index.js"

Catálogo de herramientas

El servidor expone 11 herramientas. Projekt Republic llama “tasks” a las issues; list_issues y list_tasks son el mismo endpoint (alias de conveniencia).