MIVAA API
MIVAA is the platform's application backend — the Python service that does the heavy lifting behind the product: processing supplier PDFs into structured catalogues, running the multi-vector material search and RAG, and serving the partner tracking APIs (prices, brand mentions and jobs) that other projects integrate with. It's a documented REST API with a live OpenAPI spec.
Base URL & live documentation
| What | Where |
|---|---|
| Base URL | https://v1api.materialshub.gr |
| Swagger UI (interactive) | https://v1api.materialshub.gr/docs — browse and try every endpoint in the browser. |
| ReDoc (reference) | https://v1api.materialshub.gr/redoc — a clean, readable reference view. |
| OpenAPI spec (machine-readable) | https://v1api.materialshub.gr/openapi.json — generate a client from it. |
The spec is generated from the running service, so it's always current. Use the tag filters in Swagger to jump to a family of endpoints (e.g. Mention Tracking (Public API)).
Authentication
Which credential you use depends on who you are:
| Credential | Used by | How |
|---|---|---|
| Session JWT | The MaterialsHub app itself (a signed-in user). | Authorization: Bearer <jwt>. Requests are bound to the caller's workspace. |
Partner API key (kai_*) | You, integrating from another product. | Authorization: Bearer kai_.... Generate and test keys in Profile → Subscription → API Keys. |
| Platform key / cron secret | Internal server-to-server & scheduled jobs. | Not for third-party use. |
Keys are workspace-scoped and metered. A kai_* key acts for the workspace that owns it, and billable operations debit credits from that owner's balance (each endpoint documents its cost). Deleting a key cascades — it also removes the tracked subjects created with it.
What's on the API
- Partner tracking APIs — the ones designed for external integration:
- Price tracking —
/api/v1/prices/track/*: track a product/query, refresh it, read price history and retailer results. - Mention tracking —
/api/v1/mentions/track/*: track a brand/keyword across news, blogs, RSS, YouTube and LLMs; read the feed, summary and LLM-visibility snapshot. - Job tracking —
/api/v1/jobs/track/*: recurring job discovery with matches and digests.
- Price tracking —
- Catalogue & document processing — upload a supplier PDF and get back structured products, images and knowledge (the pipeline behind the Knowledge Base).
- Search & RAG — the multi-vector material search and knowledge-base retrieval that powers the assistant.
- Admin/operational endpoints — internal, admin-gated; not part of the partner surface.
Calling it — a quick example
Every partner call is a normal HTTPS request with your key in the header:
| Step | What to do |
|---|---|
| 1. Get a key | In Profile → Subscription → API Keys, generate a kai_* key (shown masked afterwards — copy it once). |
| 2. Send it | Add the header Authorization: Bearer kai_your_key to each request. |
| 3. Find the endpoint | Open /docs, filter by the tag you need, and use Try it out to see the exact request/response. |
| 4. Watch the cost | Metered operations debit credits — check your balance in Credits. |
Looking for something simpler? If you only need to publish your open roles, use the key-less Public Jobs API instead. For reading your own workspace records, the Supabase API is usually the shorter path.