canonical: https://jentic.com/apis/omnimind.ai/omnimind

# OmniMind API

Jentic publishes the only available OpenAPI specification for OmniMind API, keeping it validated and agent-ready. The OmniMind API gives applications a managed RAG-style platform for building project-scoped knowledge bases from URLs, files, and text, then querying them via search, ask, map, and reduce actions. It exposes 28 endpoints covering project CRUD, training ingestion (web URLs, file URLs, raw text), training progress streams, knowledge QA pair management, and four action endpoints (search, ask, map, reduce) plus a global ask. Authentication supports both bearer tokens and the omni_key header.

## For AI agents

Build per-project knowledge bases from URLs, files, and text, then ask, search, map, or reduce over them - a managed RAG layer for AI applications.

## Scope

Does not handle raw embedding storage, model fine-tuning, or speech and vision tasks - use for project-scoped RAG ingestion and querying only.

## Capabilities

- Create projects that act as isolated knowledge containers
- Train a project from a list of web URLs, files via URL, or raw text
- Stream training progress events to monitor long-running ingestion jobs
- Manage curated QA pairs that override or complement the trained corpus
- Search a project's indexed knowledge for relevant chunks
- Ask a natural-language question scoped to one project or globally
- Run map and reduce actions to apply a prompt over project records and aggregate results

## Use cases

### Internal Knowledge Base Q&A

An internal helpdesk uses POST `/projects/{id}/training/website` to ingest the company knowledge centre, then POST `/projects/{id}/actions/ask` to answer staff questions in natural language. The project-scoped design ensures different teams get answers from their own corpus rather than shared knowledge.

Example prompt: Create a project, train from 30 internal-docs URLs via POST `/projects/{id}/training/website`, then ask 'how do I request VPN access' via POST `/projects/{id}/actions/ask.`

### Bulk Document Processing with Map and Reduce

When a project contains many records (support tickets, transcripts, contracts), POST `/projects/{id}/actions/map` applies a prompt to each record (e.g. extract sentiment) and POST `/projects/{id}/actions/reduce` aggregates the per-record outputs into a single answer. This is a managed equivalent of a RAG pipeline's batch-summarise step.

Example prompt: Run POST `/projects/{id}/actions/map` with a sentiment-extraction prompt across 200 support tickets, then POST `/projects/{id}/actions/reduce` to roll up overall sentiment trends.

### Curated QA Override of Trained Corpus

Teams that want authoritative answers for specific questions add curated QA pairs via POST `/projects/{projectId}/knowledge/qa.` These pairs take precedence over the trained corpus when the question matches, so legal-vetted phrasings do not get rewritten by the model. Update or remove pairs via PATCH and DELETE on the same path.

Example prompt: POST a QA pair with question 'what is our SLA' and the legal-approved answer to `/projects/{projectId}/knowledge/qa` for the customer-success project.

### AI Agent RAG Backend via Jentic

An AI agent integrated through Jentic uses OmniMind as its retrieval backend - no need to set up vector DBs, embeddings, or chunking. The agent calls POST `/projects/{id}/actions/search` to fetch relevant chunks or POST `/actions/ask` for direct answers. Jentic stores the bearer token or omni_key encrypted and injects it on each call.

Example prompt: Search Jentic for 'ask omnimind project', load `/projects/{id}/actions/ask`, and execute it with the question 'how do I configure SSO' against the docs project.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/projects` | Create a new project |
| POST | `/projects/{id}/training/website` | Train a project from web URLs |
| POST | `/projects/{id}/actions/ask` | Ask a natural-language question scoped to a project |
| POST | `/projects/{id}/actions/search` | Search project knowledge |
| POST | `/projects/{id}/actions/map` | Apply a prompt to each project record |
| POST | `/projects/{id}/actions/reduce` | Reduce per-record outputs into a single result |

## Key resources

- **Projects** — Create and manage isolated knowledge containers; list, retrieve, update, and delete projects.
- **Training** — Ingest content from web URLs, file URLs, and raw text; monitor and cancel training jobs; stream progress.
- **Knowledge QA** — Curate QA pairs that complement or override the trained corpus.
- **Actions** — Search, ask, map, and reduce over a project's knowledge; ask globally across all projects.
- **Resources** — List the URLs that have been ingested into a project.

## Why Jentic

- **Setup:** Wiring the OmniMind API by hand means choosing between a bearer token and the omni_key header, setting the right auth scheme on every call, and building each project action against app-api.omnimind.ai yourself. Through Jentic you install once, import the OmniMind API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** OmniMind puts the project id in the URL path (`/projects/{id}/actions/ask`, `/projects/{id}/actions/search`), so a rule can pin your agent to one project: it can query and search that project and nothing else. You choose the operations it may call, so training ingestion or project creation are not included unless you add them.
- **Credential handling:** Your OmniMind bearer token or omni_key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'ask a question on omnimind' or 'train omnimind from a url', and Jentic returns the matching OmniMind action with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenAI API** — General-purpose LLM API; pair with your own retrieval layer for RAG.
- **Pinecone API** — Managed vector database for storing embeddings used in custom RAG flows.
- **Cohere API** — LLM and embeddings API with strong multilingual support.

## FAQ

### Why is there no official OpenAPI spec for OmniMind API?

OmniMind does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call OmniMind API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the OmniMind API use?

OmniMind supports two schemes: HTTP bearer (Authorization: Bearer ...) and the omni_key API-key header. Jentic stores either credential in its encrypted vault and chooses the configured one per project at call time.

### Can I train an OmniMind project from a list of URLs?

Yes. POST `/projects/{id}/training/website` accepts a list of URLs and starts a training job. Use GET `/projects/{projectId}/training/{trainingId}/stream` to monitor progress in real time, or PATCH `/projects/{id}/training/{trainingId}/cancel` to abort if the wrong URLs were submitted.

### What are the rate limits for the OmniMind API?

Rate limits are not declared in the OpenAPI spec. Training endpoints are bounded by ingestion throughput rather than request rate; action endpoints (ask, search, map, reduce) follow standard fair-use throttling.

### How do I ask a question against a specific project through Jentic?

Search Jentic for 'ask question on omnimind project', and the SDK returns POST `/projects/{id}/actions/ask.` Provide the project ID and the question - the answer comes back grounded in that project's corpus.

### Does OmniMind expose embeddings or chunk-level vectors directly?

Not via this REST API. The Search action returns ranked chunk content, but raw embedding vectors and chunking strategy are managed inside OmniMind. Use Pinecone or a similar vector DB if you need direct vector access.

### Can I limit what my agent is allowed to do with the OmniMind API?

Yes. Because you run Jentic One yourself, your own rules decide which OmniMind operations and credentials the agent may use. OmniMind carries the project id in the URL path, such as `/projects/{id}/actions/ask` and `/projects/{id}/actions/search`, so you can pin the agent to a single project and let it only query and search that one. You also choose the operations it may call, so higher-impact actions like training ingestion or project creation stay off the table unless you explicitly add them.