canonical: https://jentic.com/apis/app.nanonets.com/nanonets

# NanoNets

The NanoNets API lets developers build, train, and run custom deep-learning models for image classification and OCR without managing infrastructure. Operations cover creating a model, uploading and labelling training files or URLs, kicking off training, and submitting prediction requests on hosted models. Models progress through state IDs from creation through training to hosted (state 5), where they accept inference traffic.

## For AI agents

Train custom OCR and image classification models on uploaded examples, then run predictions on new images so an agent can extract structured fields from documents.

## Scope

Does not handle natural-language generation, text translation, or speech transcription - use for image classification and OCR model training and inference only.

## Capabilities

- Create an OCR or image classification model via `/OCR/Model` or `/ImageCategorization/Model`
- Upload training files or remote URLs to a model with /UploadFile and /UploadUrls
- Label training examples through /LabelFile and /LabelUrls before training
- Trigger model training and poll the model state until it reaches hosted (5)
- Run OCR predictions against a hosted model to extract structured fields
- Pull full-text OCR from images via `/OCR/FullText` without training a custom model
- Retrieve image-level inferences within a date interval for audit and accuracy tracking

## Use cases

### Custom Invoice OCR Pipeline

Train a NanoNets OCR model on a few hundred labelled invoices, then route incoming PDFs through the hosted model to extract vendor name, total, line items, and dates as structured JSON. The full lifecycle is covered: POST `/OCR/Model` creates the model, `/OCR/Model/{id}/UploadFile` uploads training images, /LabelFile attaches annotations, /Train kicks off training, and predictions run once state reaches 5.

Example prompt: Create an OCR model via POST `/OCR/Model`, upload 200 labelled invoice files via /UploadFile and /LabelFile, trigger /Train, poll until state=5, then call prediction on a new invoice

### Receipt Image Classification

Build an image classification model that sorts receipt photos into categories (meals, travel, supplies) using POST `/ImageCategorization/Model` and the upload/label/train flow. Once hosted, the model classifies new receipt uploads in production for expense automation, removing the per-receipt manual category step.

Example prompt: Create classification model via POST `/ImageCategorization/Model`, upload labelled receipt images grouped by category, train the model, and call predict on new receipts

### Document Full-Text Extraction

Skip custom training and use the pre-built `/OCR/FullText` endpoint to pull all visible text from an image or PDF. This suits agents that need free-form document content for downstream summarisation or RAG, where field-level extraction is not required and a generic OCR call is sufficient.

Example prompt: POST an image to `/OCR/FullText` and feed the returned text into a downstream summarisation or embedding step

### Agent-Driven Document Processing

Let an AI agent orchestrate document intake by searching Jentic for 'extract fields from a document', loading the NanoNets prediction operation schema, and calling it with the image URL. The agent never holds the basic-auth credentials and can swap to alternative OCR providers if NanoNets returns low confidence.

Example prompt: Search Jentic for 'extract fields from a document', load the OCR prediction schema, execute against the user's uploaded file, and inspect confidence scores

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/OCR/Model` | Create an OCR model |
| GET | `/OCR/Model/{model_id}` | Fetch model state and metadata |
| POST | `/OCR/Model/{model_id}/UploadFile` | Upload training file to a model |
| POST | `/OCR/Model/{model_id}/LabelFile` | Attach labels to a training file |
| POST | `/OCR/Model/{model_id}/Train` | Start training the model |
| POST | `/OCR/FullText` | Run full-text OCR without a custom model |
| POST | `/ImageCategorization/Model` | Create an image classification model |

## Key resources

- **OCR Models** — Create OCR models, upload and label files, train, and run predictions
- **Image Classification Models** — Create classification models, manage training data, and run image classification
- **Full Text OCR** — Run pre-built full-text OCR without custom training
- **Inferences** — Retrieve image-level inferences and prediction request files

## Why Jentic

- **Setup:** Wiring NanoNets by hand means setting up HTTP basic auth with your API key and following the model state machine across upload, label, train, and inference steps yourself. Through Jentic you install once, import the NanoNets API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** NanoNets puts the model id in the URL path (`/OCR/Model/{model_id}/...`), so a rule can pin your agent to one OCR model: it can upload, label, or run full-text extraction against that model. You choose the operations it may call, so training a model is not included unless you add it.
- **Credential handling:** Your NanoNets API 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 'extract fields from a document' or 'train an OCR model', and Jentic returns the matching NanoNets operation with its input schema so the agent calls the right endpoint without following the model state machine in the docs.

## Related APIs

- **Mindee API** — Mindee offers off-the-shelf invoice and receipt parsers without custom training, while NanoNets focuses on user-trained models
- **Rossum API** — Rossum is enterprise document AI focused on invoices with human-in-the-loop validation
- **OpenAI API** — OpenAI vision models can post-process NanoNets output or handle one-off extraction without a trained model

## FAQ

### What authentication does the NanoNets API use?

HTTP basic authentication using your NanoNets API key as the username (password left empty). Through Jentic the API key is stored encrypted in the vault (your Jentic One instance) and never enters agent context.

### Can I train a custom OCR model with this API?

Yes. POST `/OCR/Model` creates a model, `/OCR/Model/{id}/UploadFile` and /LabelFile attach training data, and POST `/OCR/Model/{model_id}/Train` starts training. Poll `/OCR/Model/{model_id}` until state=5 (hosted) before sending prediction traffic.

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

The OpenAPI spec does not publish per-second rate limits. Limits are governed by your NanoNets plan tier and applied at the inference and training-throughput level - check the NanoNets pricing page for your account's quota before high-volume runs.

### How do I run document OCR through Jentic?

Run pip install jentic, then search 'extract fields from a document'. Jentic returns the relevant `/OCR/Model` prediction operation or `/OCR/FullText` with input schemas - load the schema, send the image URL or file, and execute.

### What model states should I expect during training?

Models progress through numeric states: 0 created (no training data), 1 data uploaded (needs annotation), 2 annotated (ready to train), 3 in training queue, 4 currently training, 5 hosted (ready for prediction), 6 retraining with new data. State -1 indicates a training error.

### Do I need a custom model for simple text extraction?

No. `/OCR/FullText` returns all visible text from an image or PDF without training. Use a custom `/OCR/Model` only when you need structured fields (invoice number, total, line items) rather than raw text.

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

Yes. Because you run Jentic One yourself, your own rules decide which NanoNets operations and credentials the agent may use. Since NanoNets carries the model id in the URL path (for example `/OCR/Model/{model_id}/UploadFile`), you can pin the agent to a single OCR model and allow only the operations you choose, such as uploading files, labelling them, or running `/OCR/FullText` extraction. Higher-impact operations like `/OCR/Model/{model_id}/Train` stay off limits unless you add them to the agent's allowed set.