Use the API and OpenAPI reference

Honen's Connector API exposes workspace commands for courses, knowledge, learning, analytics, and other permitted resources. A Connector policy controls which commands and resources its credentials can access.

Open or download the specification

• Browse the academy API reference.
• Download the current OpenAPI JSON.
• Connect an AI client to Honen.

The specification is generated from the live command registry. Import its URL into an OpenAPI-compatible client to inspect request schemas, authentication, and response shapes. The academy's imported reference is a snapshot; the JSON endpoint reflects the deployed API.

Prepare a Connector

1. Open Organization → Integrations and the Connector/MCP controls.
2. Give the Connector a descriptive name and select the resources it needs.
3. Start with read access to the specific courses or Knowledge Base folders your integration will use.
4. Create and store the credential securely. Use its Bearer token from your server or trusted development environment.

The AI client connection walkthrough shows the related access setup. A Connector does not inherit unlimited workspace access.

Make a request

Commands use POST https://honen.com/api/v1/{domain}/{action} with a JSON body. For example, a Connector with the corresponding analytics permission can request:

curl --request POST https://honen.com/api/v1/analytics/hero \
  --header "Authorization: Bearer $HONEN_CONNECTOR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{}'

A successful response has success: true and a data value. Failures have success: false and an error object. Read each operation's schema rather than assuming every command accepts the same fields or pagination.

Retry safely

Mutating commands support an Idempotency-Key header. Reuse the same key and body when retrying the same intended write. A conflicting or in-progress key can return 409; do not replace it with a new key until you understand whether the original action completed.

For asynchronous Knowledge Base imports, follow the returned job ID with kb/import-status until it reports READY or FAILED. For video walkthroughs, also inspect walkthroughStatus to follow visual processing separately from transcript extraction.

Connect learning and business outcomes

Bring learning records into your reporting environment to compare training with approved operational measures, such as onboarding milestones or support readiness.

1. Define the learning cohort, reporting period, and business measure you want to compare.
2. Create a Connector with the required analytics access. Use POST /api/v1/learning/completions to retrieve completion events. Filter by courseId, userId, or groupId as needed.
3. Send page and limit, then advance pages until pagination.page reaches pagination.totalPages.
4. Keep the returned userId, courseId, completedAt, and avgScore. The response also includes learner name/email and course title for authorized reporting.
5. In your approved warehouse or BI workflow, map the Honen learner to the corresponding business-system record using a maintained identifier mapping. Align the reporting dates before comparing results.
6. Use performance/student for a learner’s course performance, or learning/course-detail for a course/group rollup, when you need more context than a completion event.

For example, join a fictional learner’s course completion date to their onboarding-milestone date to report time from training to that milestone. Keep the learning measure and business measure labeled separately so readers can interpret the relationship.

If you use an external CRM MCP connection, choose tools and scopes that expose the records needed for the analysis. Integrations and MCP explains external tool connections. The export-and-join workflow above works with your approved reporting system and its own data-access controls.

Check your setup

The stable Connector contract is /api/v1. Dashboard session APIs, LMS launch endpoints, and xAPI use their own authentication and protocol contracts. They are not interchangeable with Connector commands. Use the current OpenAPI specification for each command’s authentication, request, and response contract.

For end-user learning delivery protocols, use LMS Integrations. For source ingestion, see Import files and web links.