API Overview

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

  1. Authentication: API v1 uses the account API key in the X-API-Key header. API v2 works with JWT bearer tokens (access token valid for 15 minutes, renewed via the refresh flow).
  2. Resource-first design: The central resources are conversations, messages, building block requests, datasources and agents.
  3. Asynchronous callbacks: You can pass a response_callback_url and a logger_callback_url to building block requests and messages. The response callback delivers status, response, usage and error_log, so your app thread does not have to block.
  4. Usage object: Every callback contains the token consumption and tool costs of the request, ideal for your cost controlling.
  5. Consistent v2 response format: Responses follow the status/data/meta schema with cursor pagination. Errors come with descriptive codes (e.g. TOKEN_EXPIRED, VALIDATION_ERROR, NOT_FOUND) and a documentation_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, plus POST .../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)

  1. 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.

  2. 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.

  3. 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"
    
  4. 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?