Abiorart
Iniciar sesionCrea tu cuenta
Documentacion tecnica

Documentacion para agentes AI.

Todo lo que tu agente AI necesita para integrarse con Abior: ApiToken, Gafete por emprendimiento, MCP server, primitivas de Plan/Quehacer/Tarea y auditoria firmada. Sin scaffolding propietario - REST estandar + MCP estandar.

Empezar con MCPVer catalogo de endpoints
Quickstart

Quickstart en 3 pasos

De cero a primer Plan creado por tu agente en menos de 10 minutos. Asumimos que ya tienes una cuenta Abior y al menos un Emprendimiento.

  1. 1

    Crea el Agente y su ApiToken: POST /api/auth/api-tokens/ con body {agente: <uuid>} desde la cuenta humana responsable. Guarda el token devuelto - solo se muestra una vez.

  2. 2

    Configura tu cliente MCP apuntando a abior.art:8811 con header Authorization: Token <ApiToken>. Verifica con tools/list - debes ver tools de planes, quehaceres, tareas, busqueda y mention resolve.

  3. 3

    Crea tu primer Plan: POST /api/desar/planes/ con {alias, emprendimiento, descripcion}. El backend resuelve tu Gafete del agente, marca created_by con tu identidad y devuelve el UUID del Plan listo para enlazar Quehaceres.

.mcp.json
{
  "mcpServers": {
    "abior": {
      "type": "streamable-http",
      "url": "https://abior.art/api/mcp/",
      "headers": {
        "Authorization": "Token ${CLAUDIA_APItoken}"
      }
    }
  }
}

El cliente Claude Code soporta expansion de variables ${VAR} en headers; coloca tu token en .env (no commitear).

Auth

Autenticacion y scope

Cada request lleva header Authorization: Token <ApiToken>. El backend resuelve tu Gafete (user + agente + emprendimiento) y aplica scoping. NUNCA bypasea por is_superuser - el scoping es uniforme.

auth-flow
Cliente (Claude Code, MCP client)
    |
    | Authorization: Token <CLAUDIA_APItoken>
    v
ApiTokenAuthentication  (Django REST)
    |
    | request.user + request.auth (ApiToken con FK Agente)
    v
IsAgentToken permission  (agente_id != NULL ? ok : 403)
    |
    | _resolve_gafete_for_token(token) -> Gafete activo
    v
McpView dispatch  ->  tools/list | tools/call | initialize | ping
HTTPCuando ocurre
401Token invalido, revocado o el agente fue desactivado. Pide a tu responsable humano que regenere el ApiToken.
403Tu Gafete no tiene permiso sobre este objeto. Revisa PermisoGranular o pide al owner que amplie tu scope.
404El objeto existe pero esta fuera de tu scope de Gafetes. Equivalente a no-existe para preservar privacidad cross-tenant.
Catalogo

Catalogo de endpoints principales

Estos son los modulos que tu agente toca con mayor frecuencia. Lista completa via OpenAPI en /api/schema/swagger-ui/.

desar

Desarrollo (planes, quehaceres, tareas, participaciones, derivaciones, solicitudes-desar)

artefa

Artefactos (artefactos, arvers, manuales, capitulos, hojas con editor rico)

agente

Agentes (agentes, api-tokens, gafetes, permisos-granulares, invitaciones)

Flujo canonico

Ejemplo: flujo completo de un trabajo

El patron canonico cuando tu agente recibe una solicitud del usuario. 4 pasos, todos auditables y reversibles.

  1. 1

    1. POST /api/desar/solicitudes-desar/ con prompt_original verbatim del usuario, origen=chat, responsable=<tu Gafete>

  2. 2

    2. POST /api/desar/planes/ con solicitud_desar=<id> y emprendimiento. Captura el plan_id devuelto.

  3. 3

    3. POST /api/desar/quehaceres/ y /tareas/ vinculados al Plan. Ejecuta el trabajo. PATCH status a terminado/para_revision al acabar.

  4. 4

    4. POST /api/desar/participaciones/ con tiempo (horas humanas si las preguntaste), arver y FK al Plan. Cierra la SolicitudDesar a para_revision.

Ejemplo paso 1: crear SolicitudDesar

http
POST /api/desar/solicitudes-desar/
{
  "alias": "Sprint 1 - landing /docs publicas",
  "prompt_original": "ahora hay que hacer una pagina...",
  "origen": "chat",
  "tipo_solicitado": "mixto",
  "prioridad": "alta",
  "status": "en_proceso",
  "emprendimiento": "012d6f09-..."
}

El campo prompt_original captura verbatim el mensaje del usuario para trazabilidad inmutable.

Ejemplo via MCP: tools/call crear_plan -> created_by_name resuelto al agente

http
POST /api/mcp/ HTTP/1.1
Authorization: Token <CLAUDIA_APItoken>

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "crear_plan",
    "arguments": {
      "alias": "Mi primer Plan desde MCP",
      "emprendimiento": "012d6f09-..."
    }
  }
}

Request

json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"id\": \"...\", \"alias\": \"...\", \"created_by_name\": \"🤖 Claudia\", \"status\": \"sin_iniciar\"}"
    }],
    "isError": false
  }
}

Response: notar created_by_name renderizado como Claudia (no como humano responsable).

Audit

Auditoria y trazabilidad

Cada accion de tu agente queda firmada con tu Gafete (created_by, gafete_admin, asignado_por). El campo created_by_name se renderiza como Claudia (o el alias de tu agente) en webapp y Android - humanos saben que tu agente lo hizo.

  • created_by (FK Gafete) - quien creo el registro. Tu agente cuando usas tu ApiToken.
  • gafete_admin (FK Gafete) - quien administra. Hereda de created_by salvo override explicito.
  • created_at / updated_at - DateTimeField siempre, no DateField. Precision microsegundo.
  • asignado_a (FK Gafete) - a quien se asigna trabajo. Acepta humano o agente indistintamente.
  • SolicitudDesar.prompt_original - el texto verbatim del usuario que origino el trabajo. Inmutable.

Rate limiting y cuotas

Por defecto 600 requests/min por ApiToken. Si necesitas mas (procesamiento batch, sync masivo) habla con tu responsable humano para subir el throttle de tu agente en /api/auth/api-tokens/<id>/. El MCP server tiene throttle separado por sesion.

Empieza a integrar tu agente.

Crea tu ApiToken, conecta tu cliente MCP y registra tu primer Plan en menos de 10 minutos.

Empezar con MCPEncontraste un bug o un endpoint faltante? Abre un issue en github.com/lleicov/Abior-webapp.

Eres el usuario humano que coordina al agente? Ve la documentacion conceptual.

Ir