hermine.ai API: Your Key to AI Automation
The hermine.ai platform offers a variety of features in the frontend, from agent workflows and knowledge bases to website chatbots. With the REST API you open up these features to your own systems: CRM, ERP, data warehouse, low-code tools or classic backend services. This way you orchestrate AI-driven processes exactly where they deliver the greatest value.
Why use the API?
| Advantage | In brief |
|---|---|
| End-to-end automation | Connect document analysis, agent logic and generative output in one seamless flow. |
| Flexible triggers & callbacks | Start AI jobs via cron, events or user actions and receive results via callback as soon as they are ready. |
| Scalable & fairly limited | Rate limiting of 1000 requests per minute and IP ensures reliable operations. |
| Full feature access | Agent runs, conversations, deep research, uploads and search are also available via the API. |
| Pay-as-you-go | Identical billing model as in the frontend: token costs plus tool costs, transparently included in the usage object. |
The three API areas at a glance
| API | Purpose | Authentication |
|---|---|---|
| API v1 (integration API) | Agent runs (building block requests), conversations and messages, data sources, search, tags | Header X-API-Key with the account API key |
| API v2 (mobile/app API) | Chat client features: auth, conversations, messages, deep research, uploads, transcriptions, agents, search, theme | JWT: Authorization: Bearer <token>, access token 15 minutes, refresh token |
| Usage Export API | Usage and billing data for accounting systems, OpenAPI specification available | Dedicated API token (scopes account/all_accounts, valid for 1 year) |
API access is included in all current licenses.
Typical use cases
- Lead enrichment: A new contact is added to the CRM, the API calls a research agent, and fields such as industry and website are filled in automatically.
- Automated reports: The data pipeline completes an ETL batch, the API triggers an agent, and the result lands in the BI folder via callback.
- Conversational support: Your chat frontend sends messages to the conversation endpoints, hermine.ai processes them with knowledge base and tools and returns the finished answer.
- Quality gate in the content pipeline: A CMS hook triggers a fact and style check before publication, and the API returns OK or correction suggestions.
Core principles
-
Authentication: API v1 uses the account API key in the
X-API-Keyheader. API v2 works with JWT bearer tokens (access token valid for 15 minutes, renewed via the refresh flow). - Resource-first design: The central resources are conversations, messages, building block requests, datasources and agents.
-
Asynchronous callbacks: You can pass a
response_callback_urland alogger_callback_urlto building block requests and messages. The response callback deliversstatus,response,usageanderror_log, so your app thread does not have to block. - Usage object: Every callback contains the token consumption and tool costs of the request, ideal for your cost controlling.
-
Consistent v2 response format: Responses follow the
status/data/metaschema with cursor pagination. Errors come with descriptive codes (e.g.TOKEN_EXPIRED,VALIDATION_ERROR,NOT_FOUND) and adocumentation_url.
API v2 endpoint reference (short list)
-
Auth:
POST /api/v2/auth/sign_in,POST /api/v2/auth/oauth/exchange,POST /api/v2/auth/refresh,DELETE /api/v2/auth/sign_out,GET /api/v2/auth/me,POST /api/v2/auth/consent -
Conversations:
GET/POST/PATCH/DELETE /api/v2/conversations, plusPOST .../mark_read,GET .../llm_models,POST .../stop,POST/DELETE .../share -
Messages:
GET/POST /api/v2/conversations/:id/messages,POST .../regenerate,POST .../feedback; deep research:POST .../research/confirm,POST .../research/cancel,POST .../research/refine,PUT .../research/plan -
Uploads & transcriptions:
POST /api/v2/conversations/:id/uploads,POST/GET /api/v2/conversations/:id/transcriptions -
Agents:
GET /api/v2/agents,GET /api/v2/agents/:id,GET .../tools,GET .../conversations -
Search, theme, deep research:
GET /api/v2/search,GET /api/v2/theme,GET /api/v2/deep_research/quota
Getting access (step by step)
-
Get in touch: Write to hello@hermine.ai with your use case and the desired environment (test/production). We enable access and provide the endpoint documentation.
-
Manage your API key: You can see your account API key on the API access page under Your API key. If needed, generate a new key via Create new API key and discard old one; the old key becomes invalid immediately.
-
Test your first call: Check the connection with a simple request, for example:
curl https://app.hermine.ai/api/v1/tags \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" -
Set up callbacks and monitoring: Register your callback URLs, monitor errors and costs, then go live.
Billing
The API is billed identically to the frontend: token costs plus tool costs, transparently included in the usage object of every callback. The monthly cost limit and per-user budgets also apply to API usage, details under Billing. For machine-readable exports of your usage data, use the Usage Export API.
Tip: Start with a single, clearly defined workflow (e.g. one agent run via building block request with a callback). Once that runs, further processes can be connected in a few hours following the same pattern.
Was this page helpful?