Referencia de API

El Epismo HTTP API está disponible en https://api.epismo.ai. Los puntos finales de la aplicación se encuentran en /v1. Los puntos finales OAuth se encuentran en /oauth y rutas de metadatos conocidas. El API utiliza el mismo modelo de objetos que el servidor CLI y MCP: paquetes, pistas, alias, sugerencias, espacios de trabajo, proyectos, alcances y créditos.

Autenticación

Los puntos finales protegidos aceptan tokens de acceso OAuth como tokens de portador.

curl https://api.epismo.ai/v1/packs/search \
  -H "authorization: Bearer $EPISMO_TOKEN" \
  -H "content-type: application/json" \
  -d '{"type":"context","query":"onboarding"}'

Los puntos finales de lectura requieren ámbitos de lectura. Los puntos finales de mutación requieren ámbitos de escritura. Muchos puntos finales /v1 aceptan workspaceId como parámetro de consulta. Si se omite, la solicitud utiliza el contexto o espacio personal predeterminado del token.

curl "https://api.epismo.ai/v1/projects?workspaceId=$WORKSPACE_ID" \
  -H "authorization: Bearer $EPISMO_TOKEN"

Solicitar convenciones

• Utilice content-type: application/json para los cuerpos de solicitud JSON.
• Los puntos finales de actualización utilizan la semántica PATCH. Los campos omitidos permanecen sin cambios.
• Las fechas utilizan YYYY-MM-DD.
• Crear y actualizar llamadas use scope; las llamadas de búsqueda utilizan scopes.
• workspaceId se pasa como parámetro de consulta en puntos finales compatibles.

Mapa de puntos finales principales

Crear un paquete de contexto

POST /v1/packs
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "type": "context",
  "title": "Team onboarding",
  "scope": { "type": "personal" },
  "blocks": [
    { "title": "Where things live", "content": "Docs in Notion, code in GitHub, designs in Figma." },
    { "title": "How we work", "content": "Weekly planning on Mondays; ship behind feature flags." }
  ]
}

Los paquetes de contexto utilizan blocks. Los paquetes de flujo de trabajo utilizan type: "workflow" y steps. Pasar bloques a un flujo de trabajo o pasos a un paquete de contexto devuelve un error de validación.

Leer paquetes de manera eficiente

El paquete lee los datos del esquema de devolución de forma predeterminada. Para paquetes grandes, no solicite inmediatamente full=true a menos que el cliente realmente lo necesite todo. Lea primero el esquema y luego busque el blockIds o el stepIds seleccionados.

curl "https://api.epismo.ai/v1/packs?reference=@repo-onboarding" \
  -H "authorization: Bearer $EPISMO_TOKEN"

curl "https://api.epismo.ai/v1/packs?reference=@repo-onboarding&blockIds=b001,b002" \
  -H "authorization: Bearer $EPISMO_TOKEN"

Agregue shareUrl=true a una lectura de paquete para crear o devolver un enlace para compartir a pedido. Crear y actualizar respuestas no generan enlaces para compartir y solicitar uno no hace público un paquete privado.

Las referencias de paquetes pueden ser UUID, @alias, @handle/alias, URL compartidas o URL centrales.

Los costos de crédito API se enumeran por operación en Créditos API.

Crear pistas

Las pistas de tareas representan un trabajo concreto.

POST /v1/tracks
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "type": "task",
  "title": "Review docs",
  "scope": { "type": "personal" },
  "task": { "status": "todo", "dueDate": "2026-06-05" }
}

Los seguimientos de objetivos representan resultados.

{
	"type": "goal",
	"title": "Ship documentation v1",
	"scope": { "type": "projects", "ids": ["project-id"] },
	"goal": { "status": "on_track", "progress": 40 }
}

Los estados de las tareas son backlog, todo, in_progress y done. Los estados de los objetivos son not_started, on_track, at_risk, postponed y completed.

Búsqueda y filtros

La búsqueda de paquetes admite type, query, page, searchMode, scopes y campos de filtro como category, like, visibility, ownerId, minLikeCount, minSuccessCount, updatedAtFrom y updatedAtTo.

La búsqueda de seguimiento admite filtros específicos de tareas, como assignee, goalId, parentId y dependsOn, además de filtros específicos de objetivos, como progressMin y progressMax. También acepta searchMode.

searchMode selecciona el modo de clasificación: keyword (predeterminado) o semantic (coincidencia de palabras clave más similitud de vectores). Omítalo para la búsqueda de palabras clave.

{
	"type": "task",
	"query": "docs",
	"scopes": [{ "type": "personal" }],
	"filter": { "status": ["todo", "in_progress"] }
}

Aplicar pistas de forma masiva

POST /v1/tracks/apply puede crear, actualizar y eliminar varias pistas en una sola solicitud. Los identificadores que no son UUID crean nuevos registros y otros upserts pueden hacer referencia a ellos en la misma solicitud.

{
	"scope": { "type": "personal" },
	"upserts": [
		{ "id": "t001", "title": "Task A", "task": { "status": "todo" } },
		{ "id": "t002", "title": "Task B", "task": { "status": "todo", "dependsOn": ["t001"] } }
	]
}

Errores

Los errores se devuelven como JSON. Los errores de validación pueden incluir detalles de análisis del esquema.

Vuelva a intentar solo las respuestas 429 y 5xx transitorias, y utilice la función de retroceso.