API Reference

All endpoints accept and return JSON. Authentication uses Bearer tokens generated in the portal.

Authentication

Every request must include a Bearer token in the Authorization header. Generate tokens in the portal under any agent's API Keys tab.

Authorization header

Authorization: Bearer hc_your_api_key_here

Global scope

Works with all agents. Select All agents when generating the key. Suitable for Make.com scenarios that orchestrate across multiple agents.

Agent scope

Restricted to a single agent. Select This agent when generating. Preferred for production scenarios to limit blast radius.

Status	Code	Meaning
`401 Unauthorized`	`{ "error": "..." }`	Missing or invalid Bearer token
`403 Forbidden`	`{ "error": "..." }`	Token valid but does not have access to this agent
`404 Not Found`	`{ "error": "..." }`	Agent ID does not exist
`400 Bad Request`	`{ "error": "..." }`	Missing required fields — check the error.fields response for details

Evaluations

Submit documents or coaching transcripts for AI evaluation. Both endpoints return immediately with a pending evaluation ID — processing happens asynchronously.

POST/api/v1/ingest

Submit a document for evaluation. Claude simulates what the agent would have produced, compares it to the expected output, identifies gaps, and proposes specific context file changes.

Request Body

Parameter	Type	Required	Description
`agentId`	string	required	ID of the agent to evaluate against. Find this in the agent's API Keys tab or via GET /api/v1/agents.
`inputDocument`	string	required	The document to evaluate. Can be a single combined document containing both the input and expected output (Claude will extract them), or just the input if expectedOutput is provided separately.
`expectedOutput`	string	optional	The ideal/expected output from a human expert. If omitted, Claude extracts it from inputDocument using the combined-document mode.
`label`	string	optional	A friendly name for this evaluation. Shown in the portal's evaluation list.

Example Request

POST /api/v1/ingest
Authorization: Bearer hc_your_key

{
  "agentId": "clxyz123...",
  "inputDocument": "Call transcript:\n[Customer]: I'm not happy...",
  "expectedOutput": "The agent should have opened with...",
  "label": "Q2 deal review — Acme Corp"
}

Response

HTTP 202 Accepted

{
  "evaluationId": "cleval456...",
  "status": "pending"
}

→Returns 202 immediately. Evaluation typically completes in 30–90 seconds depending on document size.

→Track completion via the notificationWebhookUrl configured on the agent (fires when evaluation is ANALYZED with proposed changes).

→Once complete, the Karpathy wiki for this agent is automatically updated with synthesized insights.

POST/api/v1/coaching

Submit a coaching session transcript. Claude automatically extracts the situation being coached and what the coach concluded, then runs a full evaluation comparing what the AI would have produced against the coach's guidance. Insights are routed to the coaching-insights wiki page.

Request Body

Parameter	Type	Required	Description
`agentId`	string	required	ID of the agent to evaluate against.
`transcript`	string	required	Full text of the coaching session — a team call review, 1:1 manager forecasting session, deal review, or similar. No special formatting required.
`label`	string	optional	A friendly name for this coaching session.

Example Request

POST /api/v1/coaching
Authorization: Bearer hc_your_key

{
  "agentId": "clxyz123...",
  "transcript": "Manager: Let's review the Acme deal.\nRep: So the customer said...\nManager: The key thing we missed was...",
  "label": "Weekly pipeline review — Jun 3"
}

Response

HTTP 202 Accepted

{
  "evaluationId": "cleval789...",
  "status": "pending"
}

→Claude handles extraction — send the raw transcript as-is, no pre-formatting needed.

→The evaluation type is marked COACHING, so wiki updates go to coaching-insights.md rather than gaps.md.

→Works identically to /ingest after extraction — same pipeline, same proposed changes, same webhooks.

Runtime Context

Fetch the current system prompt and context files for an agent. Call this from your Make.com scenario at execution time to inject the latest context dynamically.

GET/api/v1/agents/{agentId}/context

Returns the agent's current system prompt and all context files with their full content. Use the version field to detect changes without re-fetching the full payload.

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	required	ID of the agent.

Response

{
  "agentId": "clxyz123...",
  "version": "a3f9c12d...",
  "systemPrompt": {
    "fileName": "system-prompt.md",
    "isSystemPrompt": true,
    "content": "You are a sales coaching assistant...",
    "lastModified": "2026-05-28T14:32:00.000Z"
  },
  "contextFiles": [
    {
      "fileName": "objection-handling.md",
      "isSystemPrompt": false,
      "content": "## Handling pricing objections\n...",
      "lastModified": "2026-06-01T09:15:00.000Z"
    }
  ]
}

→version is a git commit hash. Cache it and compare on subsequent calls — if unchanged, skip re-fetching the full payload.

→systemPrompt is returned separately for easy injection as the LLM system message.

→contextFiles are ordered alphabetically. Concatenate them after the system prompt when building the agent context block.

Wiki (Insights)

Access the Karpathy wiki — a persistent knowledge base that compounds insights across all evaluations and coaching sessions. Feed the full wiki payload to your Make AI agent's context for synthesized knowledge without reprocessing raw evaluation records.

Common page slugs

recommendations

Priority context changes — most actionable

gaps

Accumulated gap patterns across evaluations

coaching-insights

Patterns from coaching sessions

trends

Similarity score trajectory over time

index

Table of contents with page summaries

log

Append-only chronological record

team

Team scorecard table — all reps, scores, trends

rep-{name}

Per-rep performance history (created by scorecard ingest)

GET/api/v1/agents/{agentId}/wiki

Returns all wiki pages with full markdown content in a single call. Inject the entire payload into your Make AI agent's context — the LLM navigates [[wikilinks]] internally without additional API calls. Returns an empty array if no evaluations have run yet.

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	required	ID of the agent.

Response

[
  {
    "slug": "recommendations",
    "title": "Priority Recommendations",
    "content": "# Priority Recommendations\n\nBased on [[gaps]] and [[coaching-insights]]:\n\n1. Add pricing objection examples...",
    "updatedAt": "2026-06-01T20:14:00.000Z"
  },
  {
    "slug": "gaps",
    "title": "Gap Patterns",
    "content": "# Gap Patterns\n\n## Critical Gaps (>40% of evaluations)...",
    "updatedAt": "2026-06-01T20:14:00.000Z"
  }
]

→Pages are ordered: recommendations first, then index, then alphabetical. The first page is always the most actionable.

→[[slug]] syntax in content are cross-references to other pages in the same array — not external URLs.

→The wiki auto-updates after every evaluation and coaching session. Fetch fresh before each agent run.

GET/api/v1/agents/{agentId}/wiki/{slug}

Returns a single wiki page by slug. Use this when you only need one specific page rather than the full wiki payload.

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	required	ID of the agent.
`slug`	string	required	Page slug (e.g. recommendations, gaps, coaching-insights, trends). See common slugs above.

Response

{
  "slug": "recommendations",
  "title": "Priority Recommendations",
  "content": "# Priority Recommendations\n\nBased on [[gaps]] and [[coaching-insights]]:\n\n...",
  "updatedAt": "2026-06-01T20:14:00.000Z"
}

→Returns 404 if the page doesn't exist yet. The wiki builds incrementally — not all pages exist from the start.

Scorecards

Ingest external call scores directly from a live-scoring agent. HappyContext stores each scorecard as a structured markdown file and automatically updates per-rep and team wiki pages.

POST/api/v1/agents/{agentId}/scorecards

Submit a scored call from an external agent. Creates a DB record, writes a Karpathy-style markdown file with YAML frontmatter, and asynchronously updates the rep's performance wiki page and the team summary page.

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	required	ID of the agent this scorecard belongs to.

Request Body

Parameter	Type	Required	Description
`repName`	string	required	Full name of the rep being scored. Used to group scorecards and generate the rep wiki page (e.g. rep-sarah-johnson.md).
`score`	number	required	Overall call score from 0–100.
`passed`	boolean	required	Whether the call met the passing threshold.
`label`	string	optional	Friendly description of the call (e.g. 'Q2 forecast review — Acme Corp').
`date`	string	optional	ISO 8601 datetime of the call. Defaults to now if omitted.
`gaps`	array	optional	Array of {description, severity} objects where severity is 'critical', 'major', or 'minor'.
`strengths`	array	optional	Array of strength strings observed in the call.
`callSummary`	string	optional	Brief narrative summary of the call.
`overallAssessment`	string	optional	Coaching conclusion or overall assessment text.

Example Request

POST /api/v1/agents/{agentId}/scorecards
Authorization: Bearer hc_your_key

{
  "repName": "Sarah Johnson",
  "label": "Q2 forecast review — Acme Corp",
  "score": 78,
  "passed": true,
  "date": "2026-06-02T14:30:00Z",
  "gaps": [
    { "description": "Missed price objection reframe", "severity": "critical" },
    { "description": "Did not confirm budget authority", "severity": "major" }
  ],
  "strengths": ["Strong rapport building", "Clear next steps"],
  "overallAssessment": "Generally strong call with a gap in objection handling."
}

Response

HTTP 201 Created

{
  "id": "clsc789...",
  "repName": "Sarah Johnson",
  "score": 78,
  "passed": true,
  "createdAt": "2026-06-02T14:30:01.000Z"
}

→Returns 201 immediately. The rep wiki page (rep-sarah-johnson.md) and team.md update asynchronously in the background.

→Each scorecard is written to data/wiki/{agentId}/scorecards/{id}.md with YAML frontmatter — readable by any LLM without DB access.

→Fetch GET /api/v1/agents/{agentId}/wiki/team or /wiki/rep-sarah-johnson to get synthesized trend analysis.

GET/api/v1/agents/{agentId}/scorecards

List all scorecards for an agent, sorted by date descending. Use this to build dashboards or feed historical scores to an LLM for trend analysis.

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	required	ID of the agent.

Response

[
  {
    "id": "clsc789...",
    "repName": "Sarah Johnson",
    "label": "Q2 forecast review — Acme Corp",
    "score": 78,
    "passed": true,
    "date": "2026-06-02T14:30:00.000Z",
    "createdAt": "2026-06-02T14:30:01.000Z"
  },
  {
    "id": "clsc456...",
    "repName": "Mike Davis",
    "label": "Pipeline review — Beta Corp",
    "score": 82,
    "passed": true,
    "date": "2026-06-01T10:00:00.000Z",
    "createdAt": "2026-06-01T10:00:01.000Z"
  }
]

→Returns lightweight records only — no gaps or strengths arrays. Fetch the wiki pages for synthesized analysis.

→Combine with GET /wiki/team for an LLM-ready team summary, or GET /wiki/rep-{name} for individual rep history.

Agents

List and discover agents available to your API key.

GET/api/v1/agents

Returns all agents accessible to your API key. Global keys see all agents; agent-scoped keys return only their agent. Useful for dynamically resolving an agentId from a name in Make.com scenarios.

Query Parameters

Parameter	Type	Required	Description
`q`	string	optional	Search filter applied to agent name and description. Case-insensitive substring match.

Response

{
  "agents": [
    {
      "id": "clxyz123...",
      "name": "Sales Coach",
      "description": "Reviews sales calls against coaching methodology",
      "createdAt": "2026-05-01T10:00:00.000Z",
      "updatedAt": "2026-06-01T09:15:00.000Z"
    }
  ],
  "total": 1
}

→Agent-scoped tokens will return at most one agent (the one they are scoped to).

→Use the q parameter to resolve an agent by name: GET /api/v1/agents?q=Sales+Coach.