canonical: https://jentic.com/apis/instabase.com/instabase

# Instabase API reference

The Instabase AI Hub API runs Instabase automation apps over your documents and returns the extracted results. You upload files into a batch, including large files through a multipart upload session, then run an app or a deployment against that batch and poll the run until it completes. Run results can include confidence scores, validation results, review results, and source information, and the API also reads and writes files in AI Hub storage, manages workspace secrets, and returns audit logs.

## For AI agents

Upload documents into Instabase batches, run automation apps or deployments over them, poll run status, and fetch extracted results with confidence scores and validation results.

## Scope

Does not handle building or training Instabase apps, e-signatures, or document storage outside AI Hub. Use for uploading documents, running Instabase apps and deployments, and reading their results only.

## Capabilities

- Create a batch, upload files to it, and list or remove its files before processing
- Upload large documents in parts through a multipart session, then commit or abort it
- Run an automation app by app_name or app_id, or run a deployment by its deployment id, against a batch_id or input_dir
- Poll a run's status and fetch its results with include_confidence_scores, include_validation_results, and include_source_info
- Read, write, and remove files and folders in AI Hub storage by path
- Store and rotate workspace secrets by alias, limited to chosen workspaces with allowed_workspaces_type
- Pull audit logs for a time range or a user email

## Use cases

### Document extraction agent through Jentic

An AI agent connected through Jentic takes a set of documents, creates an Instabase batch, uploads each file, and runs the team's deployment on it. It polls the run status, then fetches the results with confidence scores so low-confidence fields can be flagged for a person to check. The bearer token stays in your own Jentic One instance, not in the agent's context.

Example prompt: Call POST `/v2/batches` with name 'march-invoices', upload each PDF with PUT `/v2/batches/{batch_id}/files/{filename}`, run POST `/v2/apps/deployments/{deployment-id}/runs` with the batch_id, then poll GET `/v2/apps/runs/{run_id}` and fetch GET `/v2/apps/runs/{run_id}/results` with include_confidence_scores true

### Large file ingestion

Scanned contracts and statement archives can be too large for a single upload. Start a multipart session with the batch_id, filename, and file_size, upload each part by number, then commit the session with action commit, or abort it if something fails. The file then sits in the batch ready for a run.

Example prompt: Call POST `/v2/batches/multipart-upload` with batch_id, filename 'archive.pdf', and file_size, PUT each part to `/v2/batches/multipart-upload/sessions/{session_id}/parts/{part_num}`, then POST `/v2/batches/multipart-upload/sessions/{session_id}` with action 'commit' and the parts list

### Run monitoring and cleanup

Operations teams list runs by app_name, deployment_id, status, or a timestamp range to find failures, then inspect each run's status. When a run is no longer needed, deleting it can also remove its input, output, logs, and database data through the delete_input, delete_output, delete_logs, and delete_db_data flags.

Example prompt: Call GET `/v2/apps/runs` with deployment_id 'dep_123' and from_timestamp set to 24 hours ago, then report the id and status of each run that did not complete

### Workspace secrets for deployments

Deployments that call other systems need credentials. The secrets operations store a value under an alias, describe it, and limit which workspaces may use it through allowed_workspaces_type of ALL, SOME, or NONE with an allowed_workspaces list, so the value is set once and referenced by alias.

Example prompt: Call POST `/v2/aihub/secrets` with alias 'erp-token', the value, and allowed_workspaces_type 'SOME' with allowed_workspaces ['finance']

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v2/batches` | Create a batch |
| PUT | `/v2/batches/{batch_id}/files/{filename}` | Upload a file to a batch |
| POST | `/v2/apps/deployments/{deployment-id}/runs` | Run a deployment |
| POST | `/v2/apps/runs` | Run an app |
| GET | `/v2/apps/runs/{run_id}` | Get run status |
| GET | `/v2/apps/runs/{run_id}/results` | Get run results |
| GET | `/v2/files/{path}` | Read a file |

## Key resources

- **Batches** — Create, list, read, and delete batches; upload, list, and remove batch files; multipart upload sessions
- **Runs** — Run apps and deployments, list runs, read status and results, delete runs
- **Files** — Read, write, inspect, and delete files and folders by path
- **Secrets** — Create, list, update, and delete workspace secrets
- **Audit logs** — Query audit log entries by time range, type, or user

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 55 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 87 / 100
  - Developer Experience & Jentic Compatibility: 58 / 100
  - AI-Readiness & Agent Experience: 31 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 73 / 100
- **View full report:** https://jentic.com/apis/instabase.com/instabase/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Instabase by hand means handling its bearer token and IB-Context header, sequencing batch uploads or multipart sessions, and polling runs before reading paginated results. Through Jentic you install once, import Instabase from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Instabase puts the deployment, run, and batch ids in the URL path (`/v2/apps/deployments/{deployment-id}/runs`), so a rule can pin your agent to one deployment and the operations you pick. You choose the operations it may call, so destructive ones like run deletion or secret updates are not included unless you add them.
- **Credential handling:** Your Instabase token 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 'run a document extraction app' or 'get Instabase run results', and Jentic returns the matching Instabase operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Google Document AI API** — Google Cloud document parsing and extraction processors
- **AWS Textract API** — Text, form, and table extraction from documents on AWS
- **Mindee API** — Document parsing APIs for invoices, receipts, and IDs
- **Rossum API** — Transactional document processing with review queues

## FAQ

### Is there an Instabase MCP server?

You don't need an MCP server to give your agent Instabase. Jentic connects it directly from the API Directory: import it, store your token once, and your agent calls it. The agent finds the batch, run, or file operation it needs on demand, so its context is not filled with tool definitions it never uses.

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

Yes. Write a rule that allows only POST `/v2/apps/deployments/{deployment-id}/runs` for your invoice deployment's id, plus GET `/v2/apps/runs/{run_id}` and GET `/v2/apps/runs/{run_id}/results.` The agent can start that one deployment and read what it produced, but it cannot touch secrets, delete runs, or write to file storage, and every call it makes is logged.

### What authentication does the Instabase API use?

Per its OpenAPI spec, the Instabase AI Hub API uses HTTP bearer authentication: send your token in the `Authorization` header as `Bearer <token>`. Most operations also accept an optional `IB-Context` header, typically your organization ID, which sets the context that run inputs and outputs are validated against. Through Jentic, the token is stored encrypted by your own Jentic One instance and injected when each call runs.

### How do I get all the results of a large Instabase run?

GET `/v2/apps/runs/{run_id}/results` is paginated. Check the has_more field in each response and pass file_offset on the next request to continue from where the last page ended, until has_more is false.

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

The OpenAPI spec does not specify rate limits; check https://docs.instabase.com for current limits.

### Should I run an Instabase app or a deployment?

The spec recommends running a deployment over running an app directly. POST `/v2/apps/deployments/{deployment-id}/runs` adds upstream and downstream integrations, deployment metrics, human review workflows, and secret and configuration management, while POST `/v2/apps/runs` runs an app by app_name or app_id.

### How do I process a batch of documents with the Instabase API through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import Instabase from the API Directory, and store your token. Your agent searches for 'run an Instabase deployment on a batch', gets the deployment run operation with its input schema, and calls it with the batch_id, then polls the run and reads the results. To run it on your own infrastructure, install Jentic One from its GitHub repo.