FirstHelm API Reference: Programmatic Control for AI Agents

The FirstHelm API is a REST API that allows AI agents and applications to interact programmatically with the FirstHelm control plane.

The API provides core operations for:

• registering agents
• logging agent activity
• evaluating constraints
• requesting approvals
• processing approvals

The API base URL is:

bash
https://api.firsthelm.dev/functions

Authentication uses a Bearer API key. The API is designed to let organisations connect their own AI agents to FirstHelm while retaining a central control layer for governance and human intervention.

Why use an API for AI agent governance?

An autonomous agent needs more than model inference. It may need to:

• identify itself
• start a mission
• propose an action
• evaluate whether the action is permitted
• request approval when required
• execute an approved action
• log the outcome

An API provides a programmatic interface for connecting those operations to a central governance layer.

This is particularly useful when organisations build agents using different frameworks. Rather than implementing separate governance logic inside every agent, the application can communicate with FirstHelm's control plane.

FirstHelm API architecture

A simplified architecture looks like this:

This architecture separates agent execution from governance decisions.

Authentication

The FirstHelm API uses Bearer authentication. A request includes an API key in the authorisation header. For example:

bash
Authorization: Bearer YOUR_API_KEY

API keys should be treated as secrets. They should not be:

• committed to source control
• embedded in public client applications
• shared between unrelated environments
• included in logs
• exposed to untrusted users

Use appropriate secret-management practices for production deployments.

Registering an AI agent

Before an agent can be governed through FirstHelm, it can be registered with the control plane. Agent registration establishes the identity of the agent and allows the platform to associate activity and governance events with that agent.

A useful agent record can provide the foundation for:

• ownership
• monitoring
• mission management
• constraints
• autonomy
• audit history

Required fields

POST /registerAgent requires both name and framework in the JSON body. If either is missing, the API returns {"error":"name and framework are required"}.

Valid framework values:

Agents are normally registered in-app (Agents → Register Agent). Programmatic registration via the API is the Custom/dev path.

Logging agent activity

Agents can send activity information to FirstHelm through the activity logging API. Logging is important because an autonomous system needs an operational record.

Useful activity information can include:

• agent identity
• action
• timestamp
• mission
• status
• outcome
• relevant metadata

Required fields

POST /logActivity requires agent_id and action_type. The action_type field only accepts these seven values — anything else returns {"error":"Invalid action_type"}:

The purpose is to make agent activity observable and auditable.

Evaluating constraints

Constraint evaluation is one of the most important API functions. An agent can submit a proposed action for evaluation before executing it. The result can indicate one of three broad outcomes:

This pattern provides a direct connection between runtime agent behaviour and organisational policy — the constraints that bound the agent.

Requesting approval

When an agent encounters an action requiring human oversight, it can request approval through the API. The approval workflow creates a control point between the agent's proposal and its execution. For example:

This allows organisations to keep humans in the loop for consequential actions without requiring humans to supervise every low-risk step.

Required fields

POST /requestApproval requires agent_id and action_description (not description). Missing action_description returns {"error":"action_description is required"}. Optional fields: risk_level and impact_level.

Processing an approval

The API provides an operation for processing an approval decision. The resulting decision can be used by the agent to determine whether it should continue.

A production integration should treat approval decisions as authoritative governance events and should avoid executing the underlying action before the required decision has been received.

Webhooks

FirstHelm's API documentation also describes webhook events that can notify external systems about important governance events. Published events include:

Webhooks are useful when an organisation wants to integrate FirstHelm events into other operational systems. For example, a constraint violation could trigger:

• an internal alert
• a security workflow
• an incident-management process
• an operations dashboard

Agent state management

FirstHelm's application interface supports operational agent controls including:

• listing agents
• viewing agents
• pausing agents
• resuming agents

This complements the API-based integration model. An organisation can therefore combine programmatic integration with human operator controls — pausing agents when needed.

Mission management

Missions provide a way to define the work an agent is expected to perform. A mission can be governed through constraints and approval requirements.

This is important because governance should apply to the agent's intended task, not merely its underlying model. For example, the same agent may perform two different missions with different risk profiles and therefore different controls.

Interventions

The control plane provides direct intervention capabilities. Depending on the situation, an operator can:

This allows the organisation to respond to changing circumstances while an agent is operating.

Audit export

Governance decisions are more useful when they can be reviewed outside the immediate runtime environment. FirstHelm provides audit export capabilities so organisations can use activity and governance records as part of their broader operational processes.

Potential uses include:

• incident investigation
• compliance evidence
• internal reviews
• governance reporting
• security investigations

Rate limits

The published FirstHelm API documentation specifies a rate limit of 60 requests per minute.

Applications should design integrations with this limit in mind. High-volume agent systems should avoid unnecessary polling and should use appropriate event-driven patterns where available.

Building a framework-agnostic agent integration

One of the benefits of an HTTP API is that the agent does not need to use a particular AI framework. A custom agent can implement the same basic governance sequence:

1. 1. Register agent
2. 2. Start mission
3. 3. Propose action
4. 4. Evaluate constraint
5. 5. If PASS → execute
6. 6. If VIOLATE → stop
7. 7. If NEEDS_APPROVAL → request approval
8. 8. Wait for decision
9. 9. Execute only if approved
10. 10. Log result

This makes the control architecture applicable to custom agent implementations as well as supported frameworks.

API governance pattern

A production architecture should keep governance checks close to consequential actions. For example:

Handling constraint violations

When a constraint is violated, the integration should fail safely. The agent should not simply ignore the result and execute the action anyway.

A suitable response may be:

• record the violation
• stop the proposed action
• notify an operator if appropriate
• reassess the mission
• wait for explicit intervention or revised instructions

This is particularly important for agents capable of long-running autonomous activity.

API security best practices

When integrating the FirstHelm API:

• store API keys securely
• use HTTPS
• avoid logging credentials
• rotate secrets appropriately
• restrict access to integration services
• validate webhook requests
• separate development and production credentials
• monitor unusual API activity
• implement appropriate retries
• respect API rate limits

FirstHelm's API is one part of the complete application security architecture. The agent, connected systems and surrounding infrastructure must also be secured.

Example governance workflow

Consider an AI purchasing agent. Its mission is to prepare purchases. The organisation defines:

• purchases below a threshold can proceed
• larger purchases require approval
• certain suppliers are prohibited
• all purchase activity must be logged

The runtime process becomes:

The agent remains useful and autonomous for routine work while consequential activity remains under human control.

API and AI agent frameworks

FirstHelm's framework-agnostic architecture means an organisation can use the control plane with different agent technologies. The published integrations include:

• OpenAI Agents
• LangChain
• CrewAI
• AutoGen
• Anthropic
• custom HTTP/webhook agents

This allows governance controls to remain consistent even when the underlying agent implementation changes.

Frequently asked questions

Building a governed AI agent with FirstHelm

A robust integration should separate four concerns:

This separation helps organisations avoid putting the entire governance burden inside the agent itself.

Final implementation checklist

Before putting an autonomous agent into production:

1. 1. Register the agent.
2. 2. Define its mission.
3. 3. Establish constraints.
4. 4. Apply least-privilege access.
5. 5. Identify actions requiring approval.
6. 6. Implement constraint evaluation before consequential actions.
7. 7. Implement approval handling.
8. 8. Log significant activity.
9. 9. Handle violations safely.
10. 10. Connect webhook events where useful.
11. 11. Protect API credentials.
12. 12. Respect rate limits.
13. 13. Test intervention procedures.
14. 14. Review audit records.
15. 15. Define an incident-response process.

Conclusion

An AI agent API should do more than connect a model to a tool. For production autonomous AI, the integration should provide a reliable connection between agent intent, organisational policy, human oversight and execution.

FirstHelm's API provides the programmatic foundation for that model. Agents can register with the control plane, log activity, evaluate constraints, request human approval and respond to governance decisions.

The result is an architecture in which autonomous AI can operate programmatically while remaining subject to explicit organisational control. See the trust overview and docs to get started.